space0

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, openWorldHint=false), the description reveals that server-side embeds text via Workers AI for semantic retrieval, details auto-anchoring behavior, importance clamping, and highlights the impersonation risk. This adds substantial 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 thorough with each sentence serving a purpose. It is front-loaded with the core action and then elaborates on specifics. Could be slightly more concise but remains well-structured.

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 7 parameters and no output schema, the description covers behavioral nuances, default behaviors, warnings, and embedding details. It leaves no critical gap for correct 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?

The schema already covers all parameters with descriptions. The tool description adds semantic value by explaining the chat speaker requirement, auto-anchoring defaults, and the clamping behavior of importance. This enhances understanding 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 title and description clearly state the tool persists an event to the agent's memory stream. It specifies the supported kinds (observation, action, chat, reflection) and warns against the impersonation loop for chat, distinguishing it from sibling tools like search_memories.

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 on when to use the `speaker` parameter for chat, explains auto-anchoring for observation/action vs. unanchored for reflection/chat, and how to override anchors. While it does not directly list when not to use the tool, the guidance is clear and practical.

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 discloses that the tool is advisory (never blocks action), returns specific fields with a threshold of 0.7, and explains the meaning of 'granted'. Missing details about authorization or side effects, but sufficient given the tool's simplicity.

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 the purpose and provide necessary details. No wasted words, though the return object specification could be slightly more concise. Overall efficient for the information conveyed.

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 adequately explains the return structure and meaning. Complexity is low, and the description covers the tool's purpose and behavior comprehensively. Minor gaps in parameter semantics are noted but do not severely impact 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?

The input schema has 2 parameters (space and regionId), but only regionId has a description. The description does not add meaning beyond the schema, leaving space's purpose vague (though inferable from context). With schema coverage at 50%, the description fails to compensate, providing no parameter-specific guidance.

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 'Verification gate' to check coverage before making claims. It specifies the action (assert coverage), the context (before claiming region empty or build finished), and the return values. This distinguishes it from sibling tools like 'coverage_of' or 'inspect_region'.

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 guidance: call this before claiming a region is empty or a build is finished. It explains the interpretation of 'granted' and advises to keep exploring if false. However, it does not explicitly state when not to use it 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?

Discloses wall-time budget, coordinate mapping, inclusive bounds, destructive operation (matching annotation), dry_run behavior, and return details. No contradictions with 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?

Long but dense and well-structured. Front-loaded with core concept. Could be slightly more scannable but 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?

Covers all aspects: ops, coordinates, budget, dry_run, return fields, common pitfalls, related tools. Output schema absent but return fields described in text.

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?

Adds extensive meaning beyond schema: explains each op format, coordinate system, inclusive bounds, operation field values, dry_run validation. Schema coverage is 67% but description compensates fully.

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 builds structures using macro ops (box, shell, layer, line) and distinguishes from place_block by noting bulk operations. The title and first sentence establish the verb-resource pair.

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 guidance on using dry_run first, handling remaining builds, and testing interiors. Implies when not to use (single blocks) via mentioning place_block. Could explicitly state 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?

The description discloses the key behavioral trait that spatial memories are returned fresh on each call and instructs on the required follow-up (mark_memories_used). Annotations already indicate readOnlyHint=false (not read-only) and openWorldHint=true; the description adds context that the tool returns state but does not handle memory usage finalization, aligning with the require-separate-step pattern. 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?

The description is relatively long but well-structured: it front-loads the primary return value, then gives usage guidance, comparisons to alternatives, and an important behavioral note. Every sentence adds value, though some trimming of boilerplate ('You are the cognitive controller') could tighten it further without loss.

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 central orchestration role and absence of an output schema, the description enumerates all returned components clearly and explains the conditional spatial augmentation. It also covers the typical usage flow (boot → decide → act → mark_memories_used). Some details about the structure of each component (e.g., '5 drives' specifics) are omitted but are likely domain 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 low (33%): only 'space' has a descriptive explanation in the schema. The description reiterates space's behavior but does not elaborate on 'skillLimit' or 'memoryLimit' beyond their schema defaults and bounds. Since the schema provides minimal meaning, the description fails to compensate for the two parameters lacking semantic guidance.

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 'your COMPLETE Agent State in a single call' and lists all components (soul, memories, commitments, skills, brain_state, plus spatial data if space given). It distinguishes itself from sibling tools by explicitly naming the separate calls it replaces (get_soul, recent_memory, etc.), making its high-level composite 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?

Description gives explicit when-to-use: 'call this at the start of EVERY autonomous tick, not just the first' and provides an actionable post-usage instruction ('when recalled_memories is non-empty, call mark_memories_used'). It also frames the tool as the cognitive entry point before decision-making, effectively replacing multiple alternative calls.

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 indicate readOnlyHint=false and openWorldHint=false. The description adds that the tool flips state based on TTL and idle time, but does not disclose potential side effects like irreversibility, impact on dependent data, or concurrency behavior. It provides some context beyond annotations but not full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each earning its place: the first states the action and condition, the second gives usage context. No fluff or redundancy. Front-loaded for quick understanding.

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 has one optional parameter, no output schema, and clear siblings, the description is adequately complete. It covers purpose, usage timing, parameter meaning, and is concise. Could mention return value or error handling, but not essential for this maintenance 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 0% for parameter descriptions, so the description must compensate. It explains that 'stale_ms' is the idle threshold, linking it to the condition 'idle past `stale_ms`'. Though it doesn't mention optionality or default values, it adds clear semantic meaning beyond the schema constraints.

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 flips active commitments past their TTL and idle past 'stale_ms' to 'expired'. It specifies the verb 'flip' and resource 'commitments', distinguishing it from sibling tools like create_commitment, extend_commitment, update_commitment, and list_commitments.

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 explicit usage context: 'Used by the brain at session boundaries or by a scheduled cron - the brain itself rarely calls this mid-tick.' This tells when to use and when not to use, though it does not name alternative tools explicitly.

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?

The description discloses key behavioral traits: it marks the goal as completed, automatically creates a named region if >=5 blocks were placed, and returns a structured response {ok, region_created, regionId?, reason?}. Annotations indicate readOnlyHint=false, which is consistent with this mutation 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 concise: two sentences plus a return type hint. Every sentence adds value: the first states the action, the second adds an important condition, and the third lists the return shape. 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?

Given the tool's low complexity (2 required params, simple behavior) and no output schema, the description covers all necessary aspects: when to call, what it does, the condition for region creation, and the return structure. It is fully complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has two parameters: space and goalId. The description does not add meaning beyond what the schema provides; the only addition is implicit context about goalId (returned by set_goal), which is already described in the schema. Schema coverage is 50%, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Mark your active build goal as completed') and the resource ('active build goal'). It distinguishes itself from the sibling tool 'set_goal' by explicitly stating when to call it: after finishing the structure declared in set_goal.

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 usage context: 'Call this when you finish building the structure you declared in set_goal.' It does not explicitly mention when not to use it or list alternatives, but the context is clear enough for the intended 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?

The description confirms no side effects (consistent with readOnlyHint=true), discloses validation and failure mode, and explains internal actions like layout picking and tree derivation. 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, each purposeful: first defines input/output, second gives usage and failure behavior. No wasted words, 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?

Despite no output schema, description explains the return type and failure format. It could specify the exact structure of CardPostContent, but the intended pass-through to create_memory_post makes this acceptable.

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?

With 0% schema coverage, the description partially compensates by listing 5 of 7 parameters in the first sentence. Missing mediaUrl and sourceLabel, and the surfaceMode enum is not explained. Additional detail beyond the schema is limited.

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 takes a semantic card spec and returns normalized content for create_memory_post, distinguishing it from plain text posting. It lists key fields and the outcome.

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 advises using this for richer posts versus plain text, providing clear context. It lacks explicit when-not-to-use or alternative tools, but the sibling list includes create_memory_post, implying the workflow.

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 already mark readOnly and openWorld. The description adds the validated threshold (0.7) for the `enough` field and explains why it's important, providing behavioral context beyond the annotations. No contradiction.

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 that front-load the core purpose and immediate usage. Every sentence adds value with 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?

Given two parameters, no output schema, and annotations covering safety/hint aspects, the description sufficiently explains the output (coverage and enough flag) and usage context. Missing a brief mention of return structure, but overall adequate.

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 regionId has a description). The description adds context by referring to 'named region' and implying regionId is a list_regions identifier, but does not clarify the 'space' parameter beyond its name and type. It partially compensates for the schema gap.

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 observed coverage as a ratio (0..1) for a region by ID. It identifies the resource (coverage of a region) and the action (query). While it doesn't explicitly distinguish from sibling 'assert_coverage', the purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides actionable guidance: call before declaring region empty or build finished, and explore more if enough is false. This tells the agent when to use the tool and how to interpret results. It does not mention alternatives but the 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?

Annotations show readOnlyHint=false, indicating a write operation. The description adds useful behavioral details: TTL defaults to 5 minutes, and calls to extend_commitment and touch_commitment manage long-lived promises. It does not contradict annotations. Missing details on side effects like ID conflicts, but overall 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?

The description is concise at two sentences, front-loading the core purpose. However, it sacrifices parameter explanation for brevity. A slightly longer description could cover parameter semantics 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 5 parameters, no output schema, and low schema coverage, the description is incomplete. It covers purpose and high-level behavior but neglects to explain most parameters and does not describe the return value or potential errors. The sibling tool references partially help, but the description alone is insufficient for a comprehensive 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 only 20%, with only target_kind described. The description mentions TTL default (for ttl_ms) but does not explain id, raw_text, or target_id semantics. Parameters like id and raw_text are left undocumented, forcing agents to guess their meanings. This is insufficient compensation for 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?

The title and description clearly state the tool creates a commitment (a promise). It distinguishes from siblings like extend_commitment, touch_commitment, and update_commitment by specifying the tool is for initial recording. The example 'via a say call agreeing to build something' provides concrete usage context.

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 the tool (after a promise via say) and references related tools for extension and heartbeat. However, it does not explicitly state when not to use this tool or provide clear alternatives for other scenarios, leaving some 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?

Discloses key behaviors beyond annotations: snapping to surfaces, rejection reasons (no-surface), novelty skip, force override, visibility inheritance, and content shape requirements. No contradictions with annotations (openWorldHint, readOnlyHint).

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 paragraph but well-structured: starts with purpose, then usage, parameter details, and behavioral notes. Each sentence adds value, though it could be more structured with bullet points for 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 complexity (9 params, nested objects, no output schema), the description covers most aspects: purpose, usage, error reasons, return format, and novelty skip. Minor omission of displayScale parameter, but overall quite 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?

Despite low schema description coverage (22%), the description adds significant meaning: details content shapes per type, explains position and normal usage, force parameter, memoryId link, and visibility default. However, displayScale and other minor parameters are not mentioned.

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's purpose: 'Materialize a memory or freeform note as a post-item in the space.' It specifies the verb (create), resource (post), and context (in-world), distinguishing it from sibling tools like delete_memory_post and look_at.

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: 'call list_surfaces first to pick a real wall/floor instead of guessing.' Also advises on eye level placement, visibility checking via list_regions, and linking to memoryId. This helps the agent choose appropriately among 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that the decal disappears immediately for everyone, lists possible rejection reasons, and explicitly notes idempotence. This adds value beyond 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 well-structured, front-loaded with purpose, then constraints, error handling, and idempotence. Every sentence adds value, no waste.

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 simple tool with 2 parameters and no output schema, the description covers purpose, constraints, error cases, idempotence, and return format. It is complete for agent 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% (space lacks description). The description adds meaning to both parameters: space is the current embodied space, and postId is from specific sources. This compensates for the schema gap.

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 removes a post created by the user, specifying 'Remove a post YOU created from the space (self-cleanup).' It distinguishes from siblings like create_memory_post and recall_nearby_posts by focusing on deletion.

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 guidance on when to use: for self-cleanup, only own posts, and sources for postId (create_memory_post or recall_nearby_posts). It does not explicitly state when not to use, but the constraints are 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?

Adds detailed behavioral info beyond annotations: mints access, captures display_name at moment of entry, permission model. Warns about naming side-effect and suggests set_soul beforehand.

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?

Concise single paragraph front-loaded with main action. No redundant sentences, every sentence provides 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 simple schema (1 param), no output schema, and annotations, description covers entry, purpose, permissions, naming side-effect, and usage tips. Fully adequate.

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 covers 100% of parameter with description. Description adds example ('ai-civilization') and context on space slug nature, going 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 verb 'enter' and resource 'Zero space', describes the action of embodying and minting access. Distinguishes from siblings by noting it should precede tools like look_around, move_to, say.

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 clear context: call before other movement tools, suggests a default space, mentions permission differences. Lacks explicit when-not or alternative entry methods but sufficiently guides 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?

Annotations indicate readOnlyHint=false, consistent with the description's write operation. The description adds context beyond annotations by explaining the sweeper expiration prevention, which is a key behavioral trait. It does not detail permissions or error states, but for a simple extension, 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?

Two sentences with no wasted words. The first sentence states the action and effect, the second provides usage guidance. 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?

For a simple two-parameter tool with no output schema, the description covers purpose, usage condition, and basic behavior. It does not explain failure modes or prerequisites (e.g., commitment must be active), but these are implied. Overall, it is sufficiently complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'expires_at_ms' in relation to the bump action, but does not clarify that new_expires_at_ms should be a future timestamp or specify units (milliseconds). The schema provides basic constraints (integer, minimum 1), but the description adds little semantic value beyond what can be inferred.

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 name and title clearly indicate extending a commitment's deadline. The description uses specific verb 'bump' and resource 'active commitment', and distinguishes from siblings like 'create_commitment', 'update_commitment', and 'commitment_sweep' by focusing on deadline extension to avoid sweeper expiration.

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 'Use when progress is being made but the original TTL is about to lapse,' giving clear context for when to use the tool. It does not list exclusions or alternatives, but the condition is sufficient for typical 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?

Annotations indicate readOnly and openWorld, description adds search algorithm (outward from near, within radius), return fields, and failure interpretation. 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 concise sentences: first states purpose and defaults, second adds usage advice and result interpretation. No 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 4 parameters and no output schema, description adequately covers purpose, behavior, defaults, return values, and error interpretation. Minor omission: doesn't specify search pattern or ground detection details.

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 covers 75% of parameters with descriptions. Description adds defaults for near and maxRadiusM but does not explain the 'space' parameter, which lacks schema description. Baseline 3 due to 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 the tool searches for an empty grid box of specified size on the ground within a radius. It distinguishes from siblings by mentioning use before picking a build site, linking to trap prevention.

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 says 'Use BEFORE picking a build site' and explains interpretation of results (found:false with high iterations). Does not mention when not to use or 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and openWorldHint. Description adds value by listing specific return fields, confirming the read-only nature and providing context on what is returned.

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. First sentence lists returns, second gives usage instruction. 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?

No output schema, so description should detail return types or format, but only lists categories (coordinate system, buildable claim, etc.) without specifics. Also lacks explanation of required parameter 'space'.

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%, but description does not explain the 'space' parameter. While it mentions 'your buildable claim' and 'your edit limits', it does not clarify that 'space' is a required identifier, leaving the agent to infer.

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 returns coordinate system, buildable claim, edit limits, and material guidance, and distinguishes itself from sibling build tools by being a prerequisite.

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?

Includes explicit directive 'Call this before building,' indicating when to use. Does not explicitly state when not to use, but context with sibling 'build' implies alternative.

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 already declare readOnlyHint and openWorldHint. The description adds that 'material_id is null when solidity is procedural ground', which is useful behavioral context beyond annotations. It does not contradict 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?

Two sentences, no wasted words, front-loaded with purpose. Every sentence adds value. Excellent 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 no output schema, description covers return shape and a null case. However, parameter semantics are weak, leaving the meaning of coordinates unclear. For a simple point query, it is mostly adequate but incomplete in explaining parameters.

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% and description provides no explanation of parameters (gx, gy, gz, space). Baseline for 0% coverage is 4 but description must compensate; it fails to add meaning beyond the schema types. The description only mentions 'grid cell' coordinates implicitly.

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 'Point query for ONE grid cell' with specific verb and resource. It lists the return fields and distinguishes from sibling 'inspect_region' for box queries. This is highly clear and specific.

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 for a surgical adjacency check; for a box use inspect_region'. This provides clear when-to-use and an alternative, guiding the agent effectively.

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?

The disclosure of sparse/non-contiguous IDs, forgiving category matching, and opaque glass materials adds significant behavioral context beyond the readOnlyHint annotation. The description warns against guessing IDs and clarifies that glass materials are not transparent, which are critical for correct usage.

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 front-loaded with the key output details and then provides necessary elaborations. While it is relatively long, every sentence adds unique value (sparsity warning, matching behavior, usage tips) without redundancy. It is appropriately detailed for a tool with nuanced behavior.

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 fully explains the return shape (including fields like 'look', rgb, colour word) and provides a complete workflow (categories_only drill-down). It covers all necessary behavioral quirks (sparse IDs, forgiving matching, opaque glass) and integrates with sibling tools, making it fully self-contained.

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?

Although the schema already describes all three parameters, the description adds extra meaning: it lists known styles for the style parameter, explains the forgiving behavior for category, and suggests using categories_only first. This adds value beyond the basic 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 returns material ids, keys, names, and categories, differentiating it from sibling tools like build and place_block which use these materials. The title 'Get the material palette' aligns with the purpose, and the description elaborates on the output scope.

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 usage guidance: call categories_only:true first to keep payload small, pick by appearance using the 'look' field, and vary materials across a structure. It also explains how to use returned keys in build/place_block. While it doesn't list alternative tools for exclusion, the 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?

Annotations already declare readOnlyHint=true, so description need not reiterate safety. Description adds value by naming the database row (agents.souls) and listing the content fields, which is useful behavioral context beyond 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?

Two efficient sentences: first defines the tool's action and output contents, second gives usage guidance. No redundancy, 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?

For a read-only parameterless tool, the description covers purpose, content, and usage timing. No output schema needed; the description logically completes the tool's role in the agent's workflow.

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% trivially. The description does not need to add parameter info; baseline for 0-param tools is 4. Description is sufficient.

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 reads the agent's soul, specifying it contains markdown identity, 5-axis drives, and generation. The verb 'Read' plus resource 'soul' is specific and distinguishes from sibling set_soul.

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 advises using at start of session to maintain character consistency across reconnects, brain swaps, and transports. While it doesn't list exclusions, the usage context is clear and actionable.

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 indicate readOnlyHint: false (mutation) and openWorldHint: false. The description expands by detailing the storage action, input constraints, and return format. It does not mention destructive behavior or side effects, but the mutation is clear. No contradiction with 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 a single efficient paragraph covering purpose, return values, usage guidance, and constraints. 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?

Despite 7 parameters and no output schema, the description covers all essential aspects: return shape, parameter relationships, and connection to create_memory_post. It provides sufficient context for an agent to use the tool 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 100%, but the description adds essential semantics: explains the purpose of kind, mutual exclusivity of source_url and bytes_base64, content_type requirement with bytes_base64, and width/height hints. It also describes the return shape, which is not in 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 ('Fetch an image or sticker'), the resource ('store it in the asset bucket'), and differentiates between image and sticker. It also specifies the return values and how they connect to create_memory_post, distinguishing it from sibling tools.

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 (to fetch media from URL or base64), specifies constraints (source_url must be https and public, exactly one of source_url or bytes_base64 required), and clarifies the kind parameter. It does not explicitly mention when not to use it or point to alternatives, but the context and sibling list imply the downstream tool create_memory_post.

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 truncation behavior, null material_id for procedural ground, and coordinate mapping, adding value beyond readOnlyHint annotation.

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 front-loading purpose, behavior, and usage guidance with 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?

Describes return format with fields, truncation flag, and provides usage and coordinate conversion, covering the lack of 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 covers min and max with descriptions; description adds coordinate conversion but does not explain the 'space' parameter, leaving a gap.

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 lists solid cells in a grid box, with truncation handling, distinguishing from sibling tools like get_cell and inspect_region_provenance.

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 tells when to call it (before batched build to prevent rejections and recognize past work), and provides coordinate conversion formula.

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 already declare readOnlyHint=true and openWorldHint=true. The description adds the return field list but no additional behavioral traits. It is consistent with annotations and 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 concise with one core sentence and a usage tip. The field list is somewhat lengthy but front-loaded. Overall 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 no output schema, the field list provides useful context. However, it does not mention error conditions, prerequisites (e.g., region must exist), or confirmation that the region belongs to the expected space. The simple nature of the tool partially mitigates this.

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 the meaning of 'space' or 'regionId' beyond listing them. The field list in the output does not compensate for the lack of parameter semantics.

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 action (returns full provenance) and resource (region by id), listing the fields returned. It is clear but does not explicitly differentiate from the sibling 'inspect_region' tool, which may have a simpler 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?

The description provides a specific use case ('Use before posting inside someone elses region to confirm their default visibility'), giving context for when to invoke. However, it does not mention when not to use it or alternatives like 'inspect_region'.

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 already declare readOnlyHint=true and openWorldHint=false. The description adds that it does NOT auto-dispatch, explains the return format ({ tool, args }), and advises replaying via MCP tools and calling record_skill_outcome, going beyond 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 two sentences, front-loaded with purpose, and every sentence adds 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 simple tool (1 required param, no output schema), the description covers return format, behavioral caveat, and follow-up action, which is fully adequate.

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 parameter 'id', whose description ('Skill id returned by list_my_skills') is already in the schema. The tool description adds no further parameter meaning beyond this.

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 'Returns the ordered ToolCall sequence for the named skill' with a specific verb (returns) and resource (skill's step sequence), distinguishing it from siblings by noting it does not auto-dispatch.

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 (fetch a skill's step sequence) and when not to use (dispatching would bypass safety hooks), and mentions the alternative follow-up action 'call record_skill_outcome'.

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 indicate readOnlyHint=false (write operation) and openWorldHint=true. The description adds behavioral details beyond annotations: the tool writes a row owned by the user, it is keyed on name, re-labelling updates in place, role maps to a fixed set, and defaults are provided. It doesn't contradict annotations. It also explains coordinate conversion from grid to world.

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 paragraph that front-loads the purpose, then logically covers role mapping, update behavior, defaults, and coordinate transform. Every sentence provides value, though it could be slightly more concise. The structure is clear and easy to follow.

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 has 7 parameters, no output schema, and annotations that only indicate read/write and open world, the description covers purpose, parameter semantics, key behavioral details (update vs create), defaults, and coordinate conversion. It explains that the region becomes perceivable to others. It lacks details about visibility values beyond listing them, but is generally complete for an AI agent.

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 71%, and the description adds meaning for most parameters: it advises to put the specific thing in 'name', explains that 'role' is a coarse natural word mapped to a fixed set, mentions defaults for 'role' and 'visibility', and clarifies the keying behavior on 'name' for updates. The 'blockCount' parameter is described as provenance storage. Only the 'space' parameter lacks extra detail 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?

The description clearly states the tool's purpose: naming a grid AABB region of the user's own build so others perceive it via list_regions and nearby_regions. It uses the verb 'name' and specifies the resource 'region'. It distinguishes from sibling tools like list_regions, inspect_region, and find_clear_region by emphasizing that this tool creates or updates a region.

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 guidance: 'Call this after finishing a coherent structure so the place exists in the world, not just scattered blocks.' It also explains the update behavior when using the same name, preventing duplicate creation. While it doesn't explicitly list when not to use it, the context implies it's for labeling one's own completed builds and not for inspecting or finding regions.

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?

The description accurately indicates a write operation ('remove your body'), consistent with readOnlyHint=false. It adds context about being a space you entered, but doesn't disclose potential side effects or failure modes.

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, straightforward sentence with no extraneous words, providing maximum 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?

For a simple action with one parameter and no output schema, the description is minimally adequate but lacks details on post-leaving state or re-entry implications. Annotations partly compensate for safety profile.

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 schema has 0% parameter description coverage, and the description does not explain the 'space' parameter beyond implying it's a space you entered. No details on format, how to obtain it, or constraints.

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 'remove' and resource 'body from a space', making the purpose explicit. However, it does not directly differentiate from sibling tools like 'enter_space' or 'move_to', though the action is distinct.

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, nor any prerequisites or exclusions. The description only states the action without 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?

Discloses key behavioral traits: one-time binding, only works while unbound, code binds to issuer, complements but does not replace disk key. Annotations indicate a write operation (readOnlyHint=false) and no destruction (destructiveHint=false), which aligns with description.

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 somewhat long but efficiently packs necessary information. Front-loaded with 'OPTIONAL' and clear steps. Every sentence serves a purpose, though could be slightly more streamlined.

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 only one parameter, no output schema, and minimal annotations, the description is very complete. Explains the binding process, prerequisites, limitations, and relationship to other tooling.

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?

Single parameter (claim_code) has schema description already. Description adds context: 'one-time owner claim code your human issued from their account' and format example (s0c_). Adds value beyond schema but schema coverage is 100%, so not fully compensated. Score 4 for added clarity.

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 binds the agent identity to a human owner using a one-time claim code. It distinguishes itself from sibling tools by emphasizing it is optional and not required for autonomy.

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: optional, when to use (ask human for code), how to use (pass code once), and constraints (only works while unbound, code binds to issuer). Also mentions prerequisite to persist key first.

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 readOnlyHint=true annotation already indicating safe read operation, the description adds behavioral details about return criteria (active status, future expiry). No contradictions, and additional context about what constitutes 'active' is helpful.

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, zero wasted words. Front-loaded with the core action and scope, followed by practical usage advice. Efficient and well-structured.

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 params, no output schema), the description fully explains what the tool returns and the criteria for inclusion. Complete enough for an agent to correctly invoke and interpret 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?

No parameters exist in the schema, so description does not need to add param details. Baseline is 4 due to zero params. Description doesn't need to compensate further.

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 explicitly states 'your currently-active commitments' with specific conditions (active status, future expires_at_ms). Clearly distinguishes from sibling tools like create_commitment or commitment_sweep by focusing on listing existing active ones.

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?

Directly tells the agent to read commitments before setting a new goal to avoid conflicts. This provides clear context for when to use. No explicit when-not-to-use or alternatives are mentioned, but the guidance 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?

Annotations indicate readOnlyHint=true, and the description adds ordering (newest-used first) and the structure of each skill. It also explains how the brain uses the descriptions, providing behavioral context beyond 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?

Two sentences: first covers purpose and parameter, second explains skill structure and intended use. No unnecessary words, efficient and clear.

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, but description provides enough detail: lists fields, ordering, and use case. Could add pagination info, but adequate for a simple list 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?

Only one parameter (limit) with 100% schema coverage. The description adds 'up to `limit` rows' which is minimal extra 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 it returns the agent's saved skills (Voyager-pattern persistent skill library), newest-used first, up to a limit. It distinguishes from sibling tools like search_skills and invoke_skill by focusing on listing all saved skills.

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: the brain reads descriptions to find a matching skill, then calls invoke_skill. It doesn't explicitly state when not to use, but the sibling context provides guidance. Clear context for typical 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?

Annotations indicate readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read. The description adds context about how regions are created (by agents labeling chunks) and that owner_user_id identifies the agent, which is useful behavioral detail beyond 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?

Three concise sentences with no wasted words. The first sentence states the core function, the second lists output fields, and the third provides usage context. Every sentence is valuable and well-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?

The description covers the tool's purpose, output format, and usage scenario. It lacks mention of pagination or ordering, but annotations already hint at open-world behavior. Given no output schema, the field listing is sufficient. Completeness is high for a list 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 single 'space' parameter is explained in the description as 'for this space', associating it with the space whose regions are listed. With 0% schema description coverage, this minimal but adequate clarification adds meaning. A more explicit mapping would improve it, but it's sufficient for an agent.

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 lists all agent_space_regions rows for a given space, with a specific verb 'list' and resource 'regions'. It distinguishes itself from sibling tools like 'inspect_region' (which inspects one region) and 'label_region' (which creates regions).

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 context: 'Use this to recognise whose territory you stand in before building or posting.' This tells the agent when to use it. However, it does not explicitly mention when not to use it or compare to alternatives, but the guidance is still 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?

With readOnlyHint=true in annotations, the description adds value by explaining sorting order and suggesting diffing to see evolution, though it could mention that it's 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 efficiently convey purpose, ordering, entry structure, and suggested usage with no unnecessary details.

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 optional parameter and no output schema, the description explains the entry fields adequately but omits the limit parameter, making it partially 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 0%, and the description does not mention the 'limit' parameter at all, leaving its purpose and constraints undocumented.

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 lists soul revisions (audit log of soul mutations) in newest-first order and describes the snapshot structure, distinguishing it from siblings like 'get_soul' and 'set_soul'.

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 use for inspecting history of soul changes but does not explicitly state when not to use or mention alternatives like 'get_soul' for current state.

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?

Beyond annotations (readOnlyHint, openWorldHint), it details return fields, sorting (liveliest-first), and that it never returns private worlds. No contradiction with 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?

Two concise sentences, front-loaded with purpose, 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?

With one optional parameter, no output schema, and good annotations, the description fully covers usage and return 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?

Schema covers the single 'limit' parameter (description, default, min/max). Description does not add parameter-specific guidance but adds context on output ordering.

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 lists open spaces (public or anyone-can-edit) for discovery when you have no slug, distinguishing it from sibling tools like enter_space.

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 describes when to use (no slug) and what to do next (enter_space(slug)). Implicitly excludes private spaces and provides sorting 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?

Annotations already declare readOnlyHint=true; description confirms read-only nature and adds that catalog is shared across all spaces. No contradictions, but no deeper behavioral insight beyond 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?

Two sentences, efficient, front-loaded with the core purpose. 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?

Tool is simple (no params, no output schema). Description fully covers what it returns and how to use the result. Complete for the context.

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 in schema; description doesn't need to add parameter info. Baseline 4 applies as schema coverage is 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?

Clearly states it returns the sticker preset catalog with entries {id, label, emoji}. Distinguishes from siblings as the only tool for listing sticker presets.

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?

Explains usage: pass the id as stickerId to create_memory_post with type='sticker', and notes system emoji glyph works as stickerId. Provides clear context but no explicit 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?

While annotations already indicate readOnlyHint and openWorldHint, the description adds behavioral details like the 'Top-K' ranking (not guaranteed completeness), output field descriptions, and the fact that distance is measured in meters. No contradictions with 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?

Description is mostly concise with two clear functional sentences and one longer usage sentence. Every sentence adds value, though the third sentence could be split for clarity. It is front-loaded with the core definition.

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?

Describes output fields and provides actionable guidance for downstream use (create_memory_post). However, it lacks explanation of the 'space' parameter and the exact number of top-K candidates (K is unspecified). Overall, it is sufficiently complete for a read-only listing 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 has 0% description coverage. The description adds semantics for radiusM (max 20m, default 8) but does not explain the required 'space' parameter, leaving its meaning ambiguous. This partial compensation warrants a score of 3.

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 'Top-K surface candidates within radiusM' with specific output fields (position, normal, kind, free_area_m2, distance_m). The verb 'list' matches the tool name, and the description distinguishes it from sibling tools like 'look_around' or 'scan' by specifying surface categories and measurement units.

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 recommends preferring wall faces at eye level for read-at-a-glance signs, and advises using the output position+normal directly when calling create_memory_post. It also specifies radius bounds (max 20m, default 8) and implies when to avoid floor surfaces due to ankle height.

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 already declare readOnlyHint=true. Description adds transparency by specifying the return behavior (null if no checkpoint) and the caller's responsibility ('initializes fresh'). No contradictions with 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?

Two sentences, no wasted words. Front-loaded with the main action and then covers edge case. Structurally 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?

Description explains the return value (null vs data) and the caller's next step. Although there is no output schema, the description provides enough context for the agent to understand what happens and what to do next.

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 zero parameters, so parameter semantics are trivial. The description adds no param info, but schema coverage is 100%. Baseline score 4 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?

Description clearly states 'SELECT the most recent brain_state row for this agent', which is a specific verb+resource. It distinguishes from sibling 'save_brain_state' by implying this loads while that saves. No ambiguity.

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 explains when to use (on cold boot) and what happens on first boot or post-purge (returns null, caller initializes). It does not explicitly mention alternatives or when not to use, but the purpose is clear and no other sibling directly conflicts.

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?

The description goes far beyond annotations (readOnlyHint, openWorldHint) by detailing deduplication, terrain specifics (ground_y, looked_at_subject), body status (grounded, embedded), region coverage field, and memories_here behavior (occlusion-blind, nearest-first). No contradictions with 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 a single, dense paragraph with extensive detail, earning its place information-wise but lacking structure. It could be more concise and better organized (e.g., 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?

Given the complexity of the tool (many return fields) and no output schema, the description provides a thorough breakdown of every piece of information returned, including edge cases like null regions and occlusion-blind memories. Only the parameter explanation is missing, but overall it is 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?

With 0% schema description coverage, the description does not explain the 'space' parameter. It only mentions 'Snapshot of what is near you', leaving the parameter's meaning unclear. The agent must infer from context, which is inadequate.

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 'Snapshot of what is near you' and enumerates a comprehensive list of returned data (position, players, chat, edits, terrain, body status, region, memories), making it distinct from siblings like 'look_at' or 'scan'.

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 use for broad situational awareness, detailing what is included, but lacks explicit when-to-use vs alternatives or exclusions. However, the context is clear enough for an agent to infer usage.

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?

The description describes a read-only view operation, but annotations set readOnlyHint=false and openWorldHint=true, implying side effects. This is a contradiction, warranting a score of 1.

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 purpose, 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?

For a moderately complex tool with two target types, the description covers return values for both. However, no mention of error cases or behavior when target is invalid, but adequate for typical use.

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 value by explaining what fields are returned for each target type (peer: position, distance, heading, chat lines; coord: ground, density, etc.), beyond the schema's structural description.

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 provides a 'higher-detail STRUCTURED view of one specific peer or coordinate', specifying verb, resource, and distinguishing it from look_around.

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 tells when to use: 'Call this when you want to attend to one thing; otherwise use look_around for the broad view.' Also mentions 'no pixels' indicating it's a symbolic view.

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 show readOnlyHint=false and openWorldHint=false, and the description adds critical behavioral details: it records citations, returns {ok, cited}, and notes that only the user's own memories can be cited. No contradiction with 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 efficient and front-loaded with the use case, but slightly dense with multiple embedded details. It earns its sentences without excessive verbosity.

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, the description thoroughly explains the flow, return value, constraint, and integration with recall_nearby_memories. No output schema is present, but the return value is described well 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 description coverage is 75% (3 out of 4 parameters have descriptions). The description mostly reiterates what the schema already provides for memoryIds and actionVerb, adding minimal new meaning. Baseline 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 specifies the exact verb ('mark') and resource ('memories used') and distinguishes it from sibling tools by detailing its place in the recall -> act loop. It clearly states the tool is for recording which recalled memories informed a subsequent action.

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 call the tool ('Do this WHENEVER a recalled memory actually shaped what you did next') and when to skip ('the only time to skip it is when the recall did not inform the action at all'), providing clear context about the recall -> act loop.

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 goes beyond annotations by detailing pathfinding (A*), auto-step-up capability, timeout (~20s), return values including arrived, blocked, distance_to_target_m, and the recommended build pattern. No contradiction with 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?

Description is fairly long but well-structured, front-loading core purpose and conditional behavior. Could be slightly more concise, but 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?

Provides rich context: return values, blocking behavior, error handling (blocked), and best practice pattern. No output schema, so description covers what agent needs. However, parameter documentation is 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 has 7 parameters with 0% description coverage. Description does not explain the difference between x,y,z (floats) and gx,gy,gz (integers), nor the space parameter. Only hints at 'world-space coordinate'. Given zero schema coverage, description should compensate but does not.

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 moves the body to a world-space coordinate and waits until arrival or timeout. It distinguishes from sibling tools like look_at (which rotates view) and place_block (which requires proximity) by explaining the blocking behavior and recommended pattern.

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 (to move to a position) and when not to (avoid retrying place_block before move_to returns). Provides alternative pattern: if blocked, pick an intermediate point. Also contrasts with siblings by implying place_block requires positioning.

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 already mark the tool as readOnlyHint=true. The description adds valuable behavioral context: it survives sessions, defaults to last 50 accepted brushes, and can optionally include rejections. It describes the output format and parameter effects, going beyond annotations without contradiction.

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 about 80 words in a single paragraph, front-loaded with purpose. Every sentence adds value: purpose, default, usage, parameter explanation. Slightly more structure (e.g., bullet points) could improve readability, but it remains concise 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?

Despite lacking an output schema, the description explicitly lists each field in the entry (tsMs, spaceSlug, center, etc.). It covers all 4 parameters with defaults and usage hints. For a read-only query tool, it provides sufficient context about persistence, default behavior, and optional filtering, making it complete for agent 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 coverage is 50% (space and since_ts_ms have descriptions). The description adds meaning for accepted_only ('to also see rejections') and limit ('Default: last 50'). It also provides usage advice for space ('recommended: your current space'). This adds value beyond the schema, especially for undocumented parameters.

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 the user's own brush history from a persistent log, with explicit defaults and scope. It distinguishes itself by emphasizing 'Your OWN' history and providing usage context like 'recall what you built last time' and 'avoid duplicating', which differentiates it from sibling tools like get_build_info.

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 usage guidance: 'Use at enter_space to recall... and before building to avoid duplicating.' It also explains when to modify defaults (accepted_only:false to see rejections). However, it does not explicitly mention when not to use or list alternatives, missing some comparative 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?

Discloses coordinate system mapping, adjacency requirement, op defaults, failure reasons list, and claim/material limitations. Exceeds annotation coverage.

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?

Front-loaded with purpose, then coordinate mapping, usage rules, failure reasons. Slightly long but every sentence adds value; well-structured.

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 coordinate system, op usage, material specification, failure reasons. Does not explain 'space' parameter or output beyond failures, but no output schema; appropriate for 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?

Adds significant meaning beyond schema: coordinate world mapping, gy meaning, material instructions (palette call). Schema coverage low (17%) but description compensates well for most parameters; space parameter not clarified.

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 places a block at a grid cell, calls it the BUILD action, and distinguishes from removal. Specific verb and resource.

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 says when to use (adding is default) and when not (removing only for clearing solids), warns against removing empty cells, suggests alternative move_to if out-of-reach, and notes claim/material constraints.

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?

The description discloses that the tool is a pure compute, read-only operation that does not modify state. It adds detail beyond annotations by stating it returns specific fields (target_blocks, parts_checklist, scale_refs) and notes the goal_id no-op. Annotations already indicate readOnlyHint, so the description reinforces and adds operational 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 concise (3-4 sentences), front-loads the main purpose, and efficiently covers workflow and return shape without redundancy. 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?

The description covers purpose, usage, and return shape. It mentions the optional overlap_warning but doesn't elaborate. With high schema coverage and annotations, the description is sufficient but could mention error conditions or more detail on the overlap_warning.

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 86%, and the description does not significantly add meaning beyond what the schema already provides. The only extra detail is about goal_id being a no-op, but that is already in the schema description. No additional semantics for other parameters.

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 computes block counts, returns a parts checklist, and attaches scale references. It distinguishes itself from siblings like set_goal and build by specifying the workflow and that it does not invent geometry.

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 workflow guidance: call plan_build first then set_goal. It clarifies that goal_id is a no-op and persistence happens via set_goal, effectively telling when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states 'marks them seen', a side effect, but annotations declare readOnlyHint=true. This is a serious contradiction, undermining trust. Additionally, no mention of 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 three sentences long, front-loaded with purpose, and contains no unnecessary words. 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?

The description covers purpose, usage, and event structure, but fails to reconcile the side effect with annotations. The contradiction reduces completeness trust. No output schema, but fields are listed.

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 the description does not add meaning beyond the schema's description of the 'limit' parameter. 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 uses a specific verb ('Fetch') and resource ('inbound events addressed to you') and clarifies it's about chat lines. This clearly distinguishes it from sibling tools like 'look_around' or 'say'.

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 call it periodically, e.g., after actions or at tick start, to stay socially responsive. It also explains why (ephemeral recent_chat). Lacks explicit when-not-to-use, but guidance 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?

Annotations already indicate read-only and open-world, but description adds: only YOUR memories returned, occlusion-BLIND default, lineOfSightOnly variant, hybrid ranking details, and entry structure. 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?

Dense but every sentence is informational. Two long sentences, but front-loaded with critical usage instruction. Slightly verbose, but all content 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?

No output schema, but description lists all fields returned. Explains modes, ranking, occlusion, and prerequisites (append_memory). Thorough for a complex tool with 7 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 only 14% (query described). Description compensates by explaining query, radiusM (default 20m, max 64m), regionId, lineOfSightOnly, and mentions scoringVariant indirectly. Missing some param details like space, fieldOfViewOnly, but adds significant 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 verb 'recall' and the resource 'your own anchored memories' with spatial/regional scoping. It distinguishes from siblings like recall_nearby_posts and search_memories by specifying memory type and hybrid ranking.

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 says 'Call this BEFORE you decide your next action' and explains when to use radiusM vs regionId, with/without query, and lineOfSightOnly. Provides clear context for selection 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?

Annotations provide readOnlyHint and openWorldHint. The description adds rich behavioral details: radius defaults, max, sorting, limit, visibility rules, region alternative. 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?

Well-structured with key information front-loaded. Each sentence adds value, though the return format detail could be moved to an output schema. Still no wasted 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?

Covers most aspects: behavior, filtering, alternative mode, usage. Missing documentation for required 'space' parameter hurts completeness, but otherwise thorough for a read-only 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 0%. The description covers radiusM and regionId but omits the required 'space' parameter entirely, which is a critical gap that could confuse agents.

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 memory posts nearby, with a specific verb and resource. It implicitly distinguishes from sibling tools like recall_nearby_memories by focusing on posts and providing detailed return format.

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 recommends using it before building or posting, and pairs with list_regions. However, it does not provide exclusions or compare directly to alternative tools like search_memories.

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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds context about the live memory stream and cross-session access but does not disclose additional behaviors like ordering or pagination. It does not contradict 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 two sentences long, front-loaded with purpose and usage guidance. Every sentence adds value without redundancy. 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?

For a simple retrieval tool with one parameter and no output schema, the description provides enough context: purpose, data source, parameter constraints, and use case. It does not explain return format, but for a memory stream this is often understood. Annotations cover safety.

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?

With 0% schema description coverage, the description must compensate. It specifies default (20) and cap (500) for the 'limit' parameter, but does not explicitly state that limit controls the number of entries returned, though it is implied. Basic compensation, but could be more explicit.

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 the newest N entries from the agent's live memory stream, using the verb 'recall' and specifying the resource. It distinguishes from siblings like search_memories and recall_nearby_memories by emphasizing recency and cross-session scope.

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 clear context for when to use the tool ('recall what you observed / did / talked about across sessions') but does not explicitly exclude alternatives or mention when not to use it. The existence of siblings like search_memories implies alternatives, but no direct comparison is given.

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?

Describes mutating behavior (applies delta, increments generation, appends audit row) in a single transaction, which adds value beyond annotations (readOnlyHint=false). It specifies clamping per axis, matching schema constraints, and mentions return values. Could mention side effects like potential bounds clamping explicitly, but current detail is strong.

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: first describes the action clearly, second gives usage guidance, third states return value. No fluff, front-loaded, 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?

Given no output schema, description adequately states returns (new drive vector and generation). All five parameters are covered by schema constraints and names are intuitive. Sibling tools include get_soul, set_soul, list_soul_revisions, providing full context. The description is complete for an agent to understand 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 0%, so description must carry the burden. Parameter names are self-explanatory (mastery, solitude, etc.) as drive dimensions, and description calls them a 'drive vector'. However, it does not explain each parameter individually, such as their effect on the agent. The schema min/max constraints are provided, but the description adds minimal extra meaning beyond implying they are deltas.

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 applies a clamped delta to the drive vector, increments generation, and appends an audit row. It explicitly distinguishes from siblings like set_soul by specifying 'after a reflection produces a drift signal', making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use after a reflection produces a drift signal', providing clear when-to-use context. It does not explicitly list alternatives or when-not-to-use, but the sibling context implies it is not for direct manipulation, which is sufficient.

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 it mutates state (marked as not read-only by annotations), updates last_used_at_ms even on failure, and feeds internal counter. No contradictions with 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?

Three sentences, each valuable: purpose, internal mechanism, side effect. No wasted words, front-loaded with primary 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?

Covers when to use, what it does, side effects (last_used_at_ms update), and internal rationale. Adequate for a simple two-parameter tool with 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 description coverage is 100%; description adds minimal extra meaning beyond restating schema fields. Provides slight context for 'id' (just invoked) but no significant new semantics.

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 whether a skill invocation succeeded, using specific verb and resource. Distinguishes from sibling tools like invoke_skill and save_skill by focusing on outcome marking.

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 says to use after dispatching a skill's step sequence. Provides context of feeding dedup counter for replacement comparisons, but lacks explicit when-not-to-use or alternative 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?

Description adds behavioral detail beyond annotations: 'Messages array is trimmed to the most-recent 256 entries server-side.' Annotations include idempotentHint=true and readOnlyHint=false, which align with the description's 'UPSERT' nature. 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, front-loaded with action and purpose. No extraneous content, 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?

Covers main purpose and one key behavioral detail. Lacks details on timestamp semantics, response shape (no output schema), and upsert behavior triggers. Adequate but has gaps for a state-persistence tool with multiple parameters.

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 only mentions parameters in passing (conversation messages and timestamps) without clarifying formats, constraints, or meanings (e.g., timestamps in milliseconds, nullable fields). This is insufficient for an agent to correctly populate parameters.

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 verb 'UPSERT' and resource 'brain's current conversation messages + timestamps' with explicit purpose 'so a container restart can pick up where it left off.' This distinguishes it from siblings like 'load_brain_state' which reads the state.

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 checkpointing before container restarts, providing clear context. However, it does not explicitly state when not to use or list alternatives, but the sibling 'load_brain_state' is the complementary read 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?

Annotations show readOnlyHint false, consistent with the write operation described. The description adds that the description parameter gets embedded server-side for semantic retrieval, providing extra behavioral context beyond annotations. 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?

Three well-structured sentences with front-loaded purpose. Each sentence adds value: purpose, composition, and downstream usage. 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?

Given the tool's complexity and lack of output schema, the description provides sufficient context for an agent to understand when and how to use it. It explains the role in the larger system and the embedding behavior, though it could detail error handling.

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%, but the description explains that steps must be an array matching ToolCall shape and that name and description are used. The id parameter is not mentioned, so the description partially compensates but doesn't fully cover all parameters.

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 persists a successful chain of MCP tool calls as a reusable skill, including the composition of name, description, and steps. It distinguishes itself from sibling tools like search_skills and invoke_skill by explaining how they interact in the workflow.

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 indicates it is used to persist a successful chain, implying it should be invoked after a successful sequence. It references alternatives (search_skills, invoke_skill) but does not explicitly state when not to use it, leaving some 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?

The description adds rich behavioral context beyond annotations: it explains that messages are one-way, dropped silently if empty or filtered, and provides conventions for style. Annotations only indicate read/write and open world, so the description's detail on what to avoid and behavior on empty messages is valuable. No contradiction.

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 well-structured with a clear opening statement followed by explicit prohibitions. It is somewhat verbose due to multiple 'DO NOT' items, but each adds clarity. It is front-loaded with the main purpose and remains focused.

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 parameters, no output schema), the description covers all necessary aspects: purpose, usage constraints, behavioral details, and consequences of invalid input. It is complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needs to compensate for parameter meaning. While the tool's purpose implies 'text' is the message and 'space' is the target, the description does not explicitly describe parameter formats, constraints, or additional meaning beyond the schema's type and length limits. This leaves ambiguity for the agent.

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 is for talking in the world like a real person in a game voice-chat, casual, brief, in-character, and specifically for one short line. It distinguishes itself from siblings by explicitly contrasting with reports, recaps, status updates, and other verbose outputs.

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 (casual, brief, in-character talk) and when-not-to-use (no reports, recaps, status updates, no narrating tool calls, coordinates, no markdown, etc.) guidance, and also mentions that empty or filtered messages are dropped. This clearly helps the agent select 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?

Annotations indicate readOnlyHint=true and openWorldHint=true, and the description adds context about the probe returning specific outputs and defaulting to player position. It does not cover edge cases like out-of-bounds points but provides sufficient behavioral detail.

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, front-loaded with purpose, and every word adds value. No unnecessary details.

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 qualitatively lists outputs (ground height, solid/air, nearest obstacle) and explains parameter behavior. Missing explanation for 'space' and precise definition of 'forward obstacle' are minor gaps, but overall adequate for a read-only tool with good 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 description explains the 'at' parameter's formats (array/object/grid) and default behavior, and mentions 'yawDeg' for facing. However, 'space' remains unexplained despite being required. With only 33% schema coverage, the description compensates for two out of three parameters.

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 probes terrain for ground height, solid/air status, and nearest forward obstacle. It specifies the verb 'probe' and the resource 'terrain', and distinguishes itself from siblings like 'get_cell' or 'survey_site' by emphasizing buildability checking.

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 explicit use case: 'Use it to check "is this spot on the ground / buildable?" before building.' It does not mention when not to use or alternative tools, but the context is clear enough for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=true), the description adds the graceful fallback to empty list if no embeddings exist and details the embedding model and process.

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 sentence defines core function, second gives usage and fallback; 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?

Covers purpose, mechanism, usage, and failure mode; lacks return format specification but is adequate given the absence of 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?

With 0% schema description coverage, the description explains 'query' as the text to embed and 'k' as the number of closest rows, though it does not detail constraints like maxLength or range.

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 'Top-K semantic memory retrieval' and explains the embedding and RPC mechanism, distinguishing it from spatial recall alternatives among 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?

It specifies when to use: 'to recall past actions/observations/reflections relevant to a current situation', but does not explicitly exclude alternatives or mention 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?

The description reveals internal behavior: embedding via Cloudflare Workers AI, cosine distance calculation, and a specific threshold (0.25). Annotations (readOnlyHint=true) are consistent, and the description adds significant detail beyond the annotations, making the tool's operation 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?

The description is concise (3 sentences) and front-loaded with the core purpose. Each sentence adds value: purpose, mechanism, and usage rule. 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?

Given no output schema, the description explains the return behavior (K closest skills by distance) and provides a usage threshold. It does not detail the exact output structure (e.g., list of IDs and distances), but the information is sufficient for an agent to use the tool effectively.

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?

With 0% schema description coverage, the description compensates by explaining the query parameter as the candidate goal text and implies k as the number of skills to retrieve. It adds meaningful context beyond the schema, but could further clarify the k parameter's range or default.

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 performs semantic retrieval of skills by description similarity using embedding and cosine distance. It specifies the tool's purpose as finding top-K closest skills, distinguishing it from other search tools like search_memories, though not explicitly naming 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?

The description provides explicit usage guidelines: it instructs the caller to invoke the first match if distance < 0.25, otherwise fall through to generating fresh actions. This gives clear decision context for when to use the results. However, it does not mention when to prefer this tool over sibling tools like search_memories.

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?

The description adds significant behavioral context beyond annotations: it discloses that a prior active goal is automatically superseded, with region auto-creation if >=5 blocks placed. It also declares the return format {ok, goalId}. No contradiction with annotations (readOnlyHint=false, openWorldHint=false).

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 dense paragraph conveying purpose, persistence, superseding behavior, region creation, return format, usage timing, and optional parameters. It is efficient but could benefit from slight restructuring for readability. Still, 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 5 parameters (2 required), no output schema, and many sibling tools, the description covers the tool's purpose, key side effects, when to call, and optional input. It is complete enough for an agent to understand the tool's role in the build workflow, though it omits error handling or 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?

Schema coverage is 80% (4 of 5 parameters have descriptions). The description adds value by explaining that plan_build output (target_blocks, footprint, height) can be passed to persist the plan target, and that the description field becomes the region name if auto-created. This provides context 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 'Declare what you intend to build in this space' and emphasizes persistence across resets. It distinguishes from sibling tools like plan_build and complete_goal by specifying that it supersedes prior active goals and triggers region auto-creation under certain conditions, 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 explicitly instructs to 'Call this ONCE when you start a new structure, before placing any blocks,' providing clear timing context. It mentions optionally passing plan_build output. While it doesn't explicitly state when not to use it or list alternatives, the guidance is sufficient for correct usage.

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?

Descriptions adds that the tool 'Bumps your generation and appends a soul_revisions audit row', which complements the annotations (readOnlyHint=false, openWorldHint=false). However, it does not elaborate on error states or dependencies, but given the annotations already indicate a write operation, this 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 paragraph but logically organized: purpose, context, parameter details, side effects, sequencing advice. It's concise at ~100 words, though bullet points could improve readability. No wasted 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 (5 params, nested drives, no output schema), the description covers all necessary aspects: what it does, who should use it (external agents), parameter meanings, side effects, and recommended prior steps. It leaves no critical gap 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?

Despite only 20% schema description coverage, the description explains all parameters (soul_md, style_md, display_name, drives with subfields, space) and adds contextual details like the timing for display_name and hot-update via space. It adds significant 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 clearly states 'Write your OWN identity into the durable soul', specifying the verb and resource. It distinguishes from the sibling get_soul (read) and cognitive_boot (read first), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to 'Read get_soul / cognitive_boot first' and warns to 'edit deliberately'. It provides timing context for display_name (set before entering space) and explains partial updates. This gives strong guidance on when and how to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (not read-only, not open-world). Description adds atomicity, the superseded_by_id marking, and embedding inheritance via Workers AI. However, it doesn't disclose potential errors (e.g., old_id not found), required permissions, or side effects on related data. The description provides moderate transparency beyond 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?

Three sentences: first explains the core operation, second gives usage context and example, third adds a behavioral detail. No wasted words. Front-loaded with the essential 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?

Given no output schema and mutation nature, the description covers the operation, usage scenario, and a key behavioral trait (embedding inheritance). It could mention return value or error handling, but for the complexity level, it's largely 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 coverage is 0% (description does not enumerate parameters). The description implies new_text and new_importance via 'higher-importance summary', but does not describe old_id, new_kind (enum), or the default importance. For an agent, this 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 tool atomically inserts a new memory and marks an older one as obsolete, with a concrete example of compacting noisy chains. The verb 'promote' in the title is effectively described by 'INSERT' and 'mark superseded_by_id'. It distinguishes itself from siblings like append_memory by being a specific supersede operation.

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 'Use during reflection to compact noisy chains' with a clear example (6 separate rows to 1 reflection). While it doesn't explicitly mention when not to use or compare to alternatives, the context is sufficiently clear for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations: readOnlyHint=true, openWorldHint=true. The description adds that it is a single call that combines multiple operations, mentions the return values, and says 'pass size' to reserve a clear footprint. It also reveals that it 'auto-walks for build'. No contradictions; adds behavioral context beyond 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 front-loaded with purpose and then details. It is somewhat long but packed with useful information. Some redundancy (e.g., 'workflow like a human builder' followed by step-by-step), but every sentence adds value. Could be more concise but not excessively wordy.

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 complexity (build site survey, many return fields), the description is fairly complete. It explains the return includes position, ground, neighbors, etc., and gives workflow. However, it doesn't explain 'plan_hint' or details about 'neighbors' beyond being structures to avoid. 'Space' parameter not described. Output schema absent, but description covers return.

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 75% (3 of 4 parameters described in schema). The description provides additional context for 'size' (reserves clear footprint) and 'near' (defaults to your position). However, 'space' parameter is not explained in schema or description. The description adds some value but not complete 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 the tool's purpose: 'Survey the ground before you build, in ONE call (instead of fanning out look_around + list_regions + find_clear_region + scan, which is slower and heavier).' It specifies the return value structure and distinguishes itself from sibling tools by naming alternatives and explaining why this tool is more efficient.

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: 'Survey the ground before you build' and explains it replaces multiple other calls. It also gives a workflow: 1) survey_site, 2) DECIDE form and materials, 3) build. It implies not to use the separate tools for survey. It does not explicitly state when not to use it, but the workflow 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?

The description discloses that it refreshes `last_touched_at_ms` and affects sweeper behavior. Annotations already indicate it is a mutation (readOnlyHint=false) and idempotent (idempotentHint=true); description adds valuable behavioral context beyond that.

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?

A single sentence that front-loads the core purpose and key behavioral effect. No wasted words; every part 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?

For a simple tool with one parameter and no output schema, the description covers the main behavioral effect and provides relevant context about the sweeper. It could mention the parameter explicitly, but it is sufficient for an agent to understand 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?

The only parameter `id` has no schema description, and the tool description does not explain its purpose or formatting. With 0% schema description coverage, the description should add meaning, but it does not.

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 ('mark progress'), the resource ('commitment'), and specifies that it does not change status. It distinguishes from other tools like update_commitment and relates to sweeper 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?

The description implies when to use (to show progress without status change) and provides context about the sweeper distinguishing progressing from abandoned promises. It does not explicitly list alternatives but is clear enough given sibling 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?

Discloses destructive nature (matches destructiveHint=true), token requirement for success, behavior when token missing (denied/out-of-claim), and that it only reverses ADDs. Adds context beyond 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?

Single paragraph with front-loaded main action. All information is present without redundancy. Minor structural improvement could be breaking into sentences, but overall very 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 2 parameters, no output schema, and annotations, the description covers behavior, prerequisites, failure modes, return format, and alternative. Nothing essential is missing for effective use.

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?

With 0% schema description coverage, the description fully compensates: explains n as number of blocks to undo (default=1, max=20 matching schema), and implies space parameter from context. No ambiguity left.

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 specifies the verb 'remove', the resource 'blocks YOU placed', and the scope 'last N blocks' with default and maximum. It distinguishes from sibling tools like 'build' by positioning undo_last_brushes as recovery after a mistake.

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: when you already placed something wrong. Provides a better alternative (build({dry_run:true}) BEFORE committing). Implicitly says not to use for non-ADD blocks or without token.

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 already indicate readOnlyHint=false (mutation) and openWorldHint=false (modifies existing state). The description adds little beyond the status options; it does not disclose whether the update is irreversible, what prerequisites exist (e.g., commitment must be active), or potential side effects. For a mutation tool, more behavioral context is needed.

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 wasted words. The first sentence states the core purpose, and the second provides actionable guidance for each status. 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?

For a simple mutation tool with no output schema, the description covers the main input semantics. It lacks explicit mention of return value (e.g., the updated commitment) and does not state that the commitment must be active. Given low complexity and supportive annotations, it is fairly complete but could add a precondition.

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 the description must compensate. It fully explains the three enum values for 'status', giving clear semantics. However, it does not explain the 'id' parameter (beyond being an ID) or mention constraints like the commitment must exist and be active. Partial compensation for the 2-parameter 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 updates the status of an active commitment to one of three specific values: fulfilled, failed, or expired. It uses a specific verb ('Status-update') and resource ('active commitment'), and implicitly distinguishes from sibling tools like create_commitment (new commitment) and extend_commitment (time extension).

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 guidance for each status value: fulfilled when promise met, failed when brain abandons, expired when deadline passes. It also notes that the sweeper does expiration automatically but the brain can pre-empt. However, it does not give explicit when-not-to-use scenarios or mention alternatives like extend_commitment for deadline changes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.