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

Annotations only signal that this is not read-only, not idempotent, and not destructive; the description adds the important behavioral facts that the result is immutable and protected by a SHA-256 hash. It does not explain side effects on source entities or output details, but it meaningfully exceeds the annotations and does not contradict them.

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

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

One dense, well-structured sentence with no filler. It front-loads what the tool packages, then the key properties (immutable, SHA-256 hashed), then the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a seven-parameter tool with nested input and no output schema, the description gives a solid high-level view but does not state what the tool returns or any constraints across parameters (e.g., whether before/after snapshots must be paired). Schema descriptions cover individual fields, but the overall invocation contract is only partially specified.

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

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

All seven parameters already have schema descriptions (100% coverage), so a baseline of 3 applies. The description's high-level categories loosely map to entity_ids, observation_ids, and snapshot IDs but add no field-level semantics 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 states a specific action ('Package') applied to a specific resource (cryptographic evidence pack) and enumerates the inputs: entity positions, observation reconciliations, and snapshot states. It also names the intended purpose (compliance and state-memory task verification), which distinguishes it from the sibling data-management 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 intended context is explicit: evidence for compliance and state-memory task verification, implying use after snapshots/observations are collected. It does not name alternatives or give when-not-to-use exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint and destructiveHint=false, and the description does not contradict them. It adds modest context that outputs target Playwright MCP automation or projections, but it stops short of stating that no game state is modified or that the tool only produces action payloads rather than executing them.

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

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

The description is a single sentence with no filler and is front-loaded with the primary generation purpose. However, for a tool with 17 parameters and three action modes, the compressed wording may sacrifice clarity by omitting mode-specific context.

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 schema is richly documented, but the description provides no walkthrough of the three action modes, no required parameter combinations, and—since there is no output schema—no indication of what the returned Playwright inputs look like. It is adequate only because the schema descriptions fill most gaps.

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

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

With 100% schema description coverage, the input schema already documents all 17 parameters and their defaults. The description adds only a coarse map to parameter groups (WASD/mouse-look/clicks to control_profile, coordinates to projection parameters), which is useful but not enough to add much 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 names a concrete operation ('Generate Playwright MCP automation inputs') plus a second coordinate-conversion mode ('project/unproject 3D entity coordinates and screen pixels'). It is specific about the resource and output medium, but it does not explicitly differentiate from siblings such as simulate_movement or get_expected_view, and the two modes are folded into one sentence.

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

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

No guidance is given about when to choose generate_game_inputs over simulate_movement or get_expected_view, nor about when to use generate_inputs vs project_screen vs unproject_ray. The tool's role is only implied by the verb 'generate', so an agent must infer selection criteria from the schema.

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 destructiveHint=false, so the agent knows the tool is safe. The description adds the notion of a 'frustum cone' which clarifies the geometric calculation, but does not explain what output is returned (e.g., a list of entity IDs or count). It also does not mention any assumptions about entity position representation or coordinate system. Since annotations cover the mutation safety, this is a pass with minor gaps.

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

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

The description is a single sentence that is concise and directly states the tool's purpose. It is front-loaded with the core concept and uses domain-specific terms that are likely familiar to the target agent. No filler or redundant text.

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 is a read-only calculation with no output schema, the description is fairly complete for understanding its inputs and purpose. It lacks explicit details on return format or any edge cases, but with comprehensive parameter schemas and safe annotations, an agent can likely call it correctly. The breath of sibling tools suggests it's part of a simulation context, and the description fits in well. A minor gap is the absence of what 'visible' means in terms of occlusion or whether entities behind obstacles are considered, but this is acceptable for a 5-parameter 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 100%, so every parameter has a description in the schema. The description adds a hint about the frustum cone but does not elaborate on how parameters like fov_degrees or max_distance interact. The description effectively restates the purpose without adding new parameter-level detail. Baseline 3 is appropriate since schema is comprehensive.

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 function: calculating which entities should be visible from an observer's pose and field of view. It specifies the verb 'calculate', the resource 'entities', and the context 'observer's pose and field of view frustum cone'. It also clearly differs from sibling tools like query_entities or get_spatial_map, which are about querying or retrieving spatial info, not computing visibility.

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 its use case: when you need to know what an observer can see given a pose and frustum. It does not explicitly contrast with alternatives like query_entities, though the purpose is clear enough that an agent could infer it. There is no mention of when not to use it, but the context is sufficiently specific to avoid major confusion. This is adequate but lacks explicit routing to 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the tool can return 3D exports and summaries, but this largely restates the format enum and does not reveal extra behaviors such as cost, size limits, or how filtering interacts with exports.

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

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

The description is a single, front-loaded sentence that communicates the core purpose quickly. It is slightly dense because it compresses many output types into one list, but it contains no filler or repetition.

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 tool with zero required parameters and a fully described schema, the description is close to adequate. However, there is no output schema and no clarification of the less obvious formats like 'joint' or 'spatial_vlm', leaving some ambiguity about what the agent will receive.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description mentions gltf/obj and summary formats, which mirrors the schema's format enum, and adds no new parameter meaning beyond what the schema already documents.

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

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

The description clearly identifies the resource ('known world') and the action ('Return'), and it enumerates the main output forms: spatial layout, topological graph, 3D asset export, and environment summary. It does not explicitly contrast itself with sibling tools like get_expected_view or query_entities, so it stops short of full differentiation.

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

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

The description implies when to use the tool: when a spatial layout, graph, 3D export, or summary of the world is needed. However, it gives no explicit when-not-to-use guidance and does not name alternatives, so an agent gets only implied selection 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 indicate this is not read-only, so the description adds value by explaining that it merges detections into the world model, re-identifies objects, and boosts confidence – all behavioral effects beyond the annotations. It also hints at reconciliation analysis. It does not disclose edge cases or failure modes, but the additional context about state mutation is meaningful given annotations are sparse. 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 a single sentence that efficiently conveys the primary and secondary purposes. It is front-loaded with the main action and avoids unnecessary words. Though it is a bit dense due to the 'or' structuring, it is appropriately concise for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, nested objects, no output schema), the description is incomplete. It does not explain what the tool returns, how observer_pose and field_of_view feed into the merge/reconcile logic, or when each mode should be used. The schema descriptions help somewhat, but the overall behavior and expected outcomes are under-specified, leaving an agent uncertain about invocation and interpretation.

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 83% (high), so the baseline is 3. The description does not elaborate on individual parameters beyond the schema; it only references detections conceptually and reconcile as a mode. It does not add semantics for field_of_view, observer_pose, or visual_state_id, which the schema partially describes. The description adds marginal value over the schema, consistent with the baseline.

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 a specific action (merge detections into the world model) and a secondary reconciliation mode, distinguishing it from sibling tools like query_entities (query-only) and update_entity (general update). The verb 'merge' and resource 'world model' are specific, and the mention of re-identifying objects and boosting confidence adds precision. However, the dual purpose (merge vs reconcile) slightly dilutes focus, so not a perfect 5.

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 (when you have vision detections to ingest) but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or comparison to siblings. It does not say 'use query_entities for reading' or 'use update_entity for direct edits'. The guidance is implied rather than explicit, so it meets the minimum but lacks clear routing.

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 and destructiveHint=false, so the tool mutates state. The description adds little beyond that: it mentions 'link/unlink' which implies modification, but does not disclose what entities or DAGs are affected, whether actions are reversible, or any side effects of get_context. The behavioral transparency is weak given the tool's complexity.

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, compact sentence that leads with the primary purpose and separates the two main modes. It is free of fluff and front-loads the key information, though it could be slightly more structured for readability.

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 (10 parameters, multiple actions, nested objects, no output schema), the description is too brief. It does not explain which parameters apply to which action, what the return value looks like, or how it complements the many sibling spatial tools. An agent would need to open the schema and infer usage, which is insufficient for such a multi-mode 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 100%, so the schema already documents each parameter. The description adds a high-level context (entity/region association, goal-relevant slices) but does not clarify conditional requirements (e.g., which parameters are needed for each action) or relationships between parameters. With full schema coverage, a baseline of 3 is appropriate, but the description could have filled the conditional-usage 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 a specific verb ('associate') and resource ('entities or spatial regions' with 'state-memory task DAGs'), and also distinguishes a second operation ('extract goal-relevant spatial context slices'). It is not a tautology and differentiates from siblings by focusing on goal-DAG linking and context retrieval.

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 no guidance on when to use this tool versus alternatives like set_relation or query_entities. It does not mention prerequisites, scenarios, or conditions that should favor this tool. The action parameter (link/unlink/get_context) implies usage, but there is no explicit when-to-use or exclusions.

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

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

Annotations are all set to false and provide no safety profile, so the description carries full weight. It says 'restore' and 'undo mutations' without disclosing whether these actions destructively modify world state, whether they are reversible, or what permissions are needed. The read-only operations (list, diff, history, time travel) are not separated from mutating ones.

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

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

One dense sentence that front-loads the tool's role and enumerates actions. There is no repeated info and the structure clearly organizes the core capabilities, though the sausage is a bit sprawling.

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 9 parameters, 7 actions, and no output schema, the description is too sparse to fully map actions to required parameters or to explain return types. Each property in the schema is described, but the constellation of combinations and the tool's output shape are left to inference, so it is just 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 100% and each parameter has its own descriptions, so the schema does the heavy lifting. The description adds the list of actions but not the mapping of them to parameters; it establishes baseline about semantics without violating or contradicting 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 precisely identifies the resource (spatial snapshots/time-travel) and lists concrete verbs: save, restore, diff, list, undo, inspect. It clearly differentiates from sibling tools by focusing on snapshot management rather than entity updates, relations, or simulation.

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 frames the tool as the unified destination for snapshot operations but never states when to prefer it over a sibling or when not to use it. No exclusions or alternative conditions are mentioned, leaving the agent to infer scope from the action enum alone.

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 the tool is not read-only, not idempotent, and not destructive, but the description adds no extra behavioral context. It does not disclose side effects (e.g., overwriting existing specs, returning pass/fail for verification, or requiring specific permissions). Since the agent only knows it can modify state, but not how, the description fails to enhance transparency beyond the annotations.

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

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

The description is a single dense sentence with jargon ('Spatial SDD') and a long list of parenthetical constraint types. It is not overly long but could be clearer and more front-loaded by stating the primary actions first. Every phrase serves some purpose, but the structure buries the core action under modifiers.

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 8 parameters, nested objects, and no output schema, the description should provide an overview of what each action returns and how the tool fits into the spatial workflow. It does not explain that 'set' creates/updates a spec, 'verify' checks compliance, or 'list' enumerates specs. It also doesn't relate to sibling tools or clarify prerequisites. The description is too sparse for a tool of this complexity.

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

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

Schema description coverage is 100%, so each parameter is documented. The description adds a little context by mentioning physical constraints (min clearance, containment, occupancy), which maps to constraint types in the schema, but it does not clarify how parameters like bounds, tolerance, or constraints interact. It does not compensate for any ambiguity in the schema, so a 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 identifies the resource (Spatial SDD baseline contracts) and the primary operations (managing contracts and verifying compliance against physical constraints). It names specific constraint types (min clearance, containment, occupancy), which helps distinguish it from sibling tools like get_spatial_map or simulate_movement. However, the verb 'manage' is generic and doesn't explicitly enumerate the actions (set/verify/list) that the schema reveals.

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

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

No guidance is given on when to use this tool versus alternatives. It does not state 'use this to define a spatial spec' or 'when you need to check compliance', nor does it exclude scenarios better handled by siblings such as get_spatial_map or simulate_movement. The usage context is only implied by the tool name and schema.

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 read-only, idempotent, and non-destructive behavior, so the description carries a lower burden here. It does add context: FTS5 search, spatial proximity, and an alternative trajectory-lookup mode. However, it does not mention default limits, result ordering, pagination, or how much history is returned, which are behavioral details an agent might need.

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 the primary action and the main filtering modes, and the second sentence covers the direct entity_id path with a clear 'Alternatively'. No surplus wording or repeated structured data.

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 13-parameter tool with a well-described schema and no output schema, the description covers the two main calling patterns: bulk search and individual entity lookup. It does not explicitly state the return envelope (array vs single record) or global constraints like limits and pagination, but the description and schema together are enough for most common invocations.

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 describes all 13 parameters with 100% coverage, which sets a baseline of 3. The description groups related filters (keyword, type, region, spatial proximity, tags, status) and highlights the entity_id/history path, adding modest semantic value beyond schema descriptions but not deeply explaining any individual parameter.

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 the action 'Find entities' and then enumerates the search dimensions (keyword/FTS5, type, region, spatial proximity, tags, status), followed by a distinct second path for entity_id lookup. This clearly differentiates it from mutation or simulation siblings like update_entity, set_relation, and simulate_movement.

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 makes clear when to use the tool (to find/query entities, or to get a single entity's location/trajectory) but does not explicitly exclude other sibling tools, name alternatives, or state conditions for when another tool is more appropriate. The use-cases are implied but not compared against the rich sibling set.

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 not read-only, and the description adds useful behavioral context by mentioning it can record moving, property changes, destruction, and creation. This helps an agent understand the side-effect model beyond the annotations, though it does not discuss persistence, failure behavior, or return values.

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

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

The description is a single sentence that front-loads the core action and then adds concise clarifying examples. It is efficient and readable, though slightly more structure could have made the scope even clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters deeply nested objects scratch and no output schema, this description is adequate but thin. It communicates the core purpose and timing but does not explain the relationship between required params like success/action_name and optional state updates, nor does it guide an agent on which optional fields to populate in different outcome scenarios.

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

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

Schema description coverage is 100%, so the baseline is a 3. The description's examples loosely align with entity_id, resulting_position, property_changes, and destroyed, but it adds no parameter-level detail beyond what the schema already provides.

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

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

The description uses a specific verb and resource: 'Update the world model after an action executes' and clarifies with concrete examples like moving an entity or modifying properties. This goes well beyond a tautology, though it does not explicitly contrast with similar siblings like update_entity.

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 temporal context 'after an action executes' gives a clear sense of when to use the tool. However, it provides no guidance on when not to use it or how it differs from siblings such as update_entity, ingest_observation, or set_relation.

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 not read-only, so 'Record or update' is consistent but adds little beyond readOnlyHint=false. The description does not disclose important mutation behaviors such as action=remove, overwrite semantics, the bidirectional inverse-relationship effect, or idempotency, which are meaningful for a state-changing tool.

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

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

The description is a single front-loaded sentence that immediately states the action and resource. The relation list is somewhat redundant with the schema enum, but it is compact and helps at-a-glance understanding without bloating the text.

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 9-parameter write operation with no output schema, the description covers core purpose but leaves key behavioral semantics like the 'remove' action and 'bidirectional' flag to be discovered in the schema. Since the schema is rich and well-described, this is acceptable but not fully complete.

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

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

Schema description coverage is 100%, with each parameter already documented, including enums for relation and action. The description's relation examples echo the schema enum rather than adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description identifies a concrete action ('Record or update') and a clear resource ('spatial relationship between two entities'), with a helpful list of relation types. It is clearly distinct from read-oriented siblings like get_spatial_map or query_entities, though it doesn't explicitly differentiate from update_entity and omits the 'remove' action shown in the schema.

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 intended use is implied: use this tool when a spatial relationship between two entities needs to be recorded or updated. However, there is no explicit when-to-use vs. when-to-use-another tool guidance, and siblings like update_entity or manage_spatial_spec could plausibly overlap, leaving selection partially to inference.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a few behavioral details, such as AABB collision testing and waypoint navigation paths, but does not disclose potential side effects (e.g., whether it returns computed paths or only validates viability), error conditions, or performance implications. Given the annotation coverage, a 3 is appropriate—the description adds some context but not rich behavioral disclosure.

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

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

The description is two sentences with no fluff. The primary action (simulation and collision) is front-loaded, followed by the alternative (navigation). While it could benefit from structured enumeration of modes, the current form is efficient and reads clearly.

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 11 parameters, no required fields, and no output schema, the description is too sparse to guide an agent effectively. It does not specify which parameters apply to each mode, what the return format looks like (e.g., collision results, path coordinates), or how to select between 'navigate' and 'waypoints'. This leaves significant ambiguity for correct invocation, especially in multi-mode tools.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description provides a high-level overview but does not explain how parameters interrelate (e.g., that start_position and target_position are relevant only in navigation/waypoint mode, or that velocity and delta_position are for simulation). It adds minimal semantic value beyond the schema, and no parameter usage examples or prerequisites are provided—exactly the baseline for full 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 description clearly states a specific verb-resource pair: it simulates physical movement and tests AABB collisions, or calculates waypoint navigation paths. It distinguishes two distinct operation modes and names the specific resource (entities, coordinates, AABB). This differentiates it from sibling tools like update_entity (which likely modifies state) and get_spatial_map (which reads spatial data).

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It mentions two modes but does not explain the selection criteria (e.g., use 'simulate' when you need collision checks, use 'navigate' when planning a path). There are no exclusions or references to sibling tools. An agent must infer usage from the 'mode' parameter and surrounding context, which is insufficient for a multi-mode 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 already provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, indicating it is a mutating, non-idempotent, non-destructive operation. The description adds that it can both create and update, which is useful behavioral context beyond annotations; it implies persistence of changes)Skip. However, it doesn't disclose that 'create' auto-generates an ID (that is in schema) or that updates might overwrite existing properties in a way that could be non-destructive. With annotations covering the harmful side, the description adds some value but not extensive 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 a single sentence that is informative and front-loads the main action. It is not overly verbose; it lists key fields but not every detail, striking a balance. It could be shorter but it's efficient for the scope. It earns a 4 because it conveys the core purpose without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the input schema is rich with nested objects and 13 parametersтная. The description covers the main fields but doesn't explain the create-vs-update semantics in detail (e.g., that providing an id updates an existing entity). It also doesn't mention any return value or side effects, which is common for such tools. Given the complexity, it is minimally adequate but has gaps in clarifying behavior and prerequisites.

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%, meaning all 13 parameters have descriptions. The description lists fields like position, orientation, bounding box, custom properties, tags, and confidence, which overlaps with schema. It doesn't add new meaning beyond listing them; for instance, it mentions 'custom properties' but the schema already explains arbitrary JSON. For high coverage, baseline is 3, and the description doesn't significantly compensate.

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

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

The description clearly states a verb (Create or update) and a resource (entity in the spatial world model), and enumerates what fields can be set, distinguishing it from siblings like query_entities or set_relation. It doesn't explicitly name alternatives, but the purpose is specific enough that an agent can infer it is the primary write tool for entities.

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 dual behavior (create vs update) but does not explicitly state when to use this tool versus query_entities (for reading) or other spatial manipulation tools like manage_spatial_spec. It mentions 'create or update' but lacks explicit conditions, such as 'use when you need to add a new entity or modify an existing one's properties.' It also doesn't state when not to use it (e.g., for queries). Some usage is implied but not explicit.

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 beyond the sparse annotations by revealing that content is ephemeral and that claiming grants exclusive spatial access, which is important for collision-sensitive coordination. It doesn't spell out TTL or claim-expiry mechanics, but the word 'ephemeral' signals lifetime and 'exclusive' signals blocking semantics without contradicting any 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?

The definition is a single focused sentence with no filler. It is efficient and front-loads the core purpose, though it could have used an explicit verb and a brief note about the four action modes.

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 an 8-parameter tool with no output schema, the description does not explain how the post/read/claim/release actions map to parameters or what a read result looks like. The schema covers individual parameters, but the description alone is not enough to correctly choose between this and the many sibling spatial tools.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the action enum, payload coordinates, TTL, and duration. The description only frames semantics conceptually and does not add operational details such as which parameters apply to posting versus claiming.

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 identifies a shared spatial blackboard and names its two core purposes: publishing ephemeral intentions/waypoints and claiming exclusive spatial access. It is not merely a title restatement Durch, but it uses a noun phrase rather than an explicit operation and does not differentiate itself from sibling spatial tools like get_spatial_map or manage_spatial_spec.

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 phrase 'for publishing... and claiming... to prevent collisions' implies when an agent would use this tool, but there are no explicit use conditions, exclusions, or named alternatives. With 14 sibling tools, an agent would still need to infer how this differs from get_spatial_map or wait_for_spatial_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?

Annotations already declare readOnlyHint and idempotentHint. The description adds value beyond those by specifying the blocking/waiting behavior and the distinct state conditions (exists, active, confidence_above, in_region), which are not inferable from the annotations alone.

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, front-loaded sentence with no filler. The operative verb and resource come first, followed by a compact parenthetical enumeration of supported conditions. Every word 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 the fully described schema and safety annotations, the description covers the core purpose and wait semantics well. The only minor gap is that it does not explicitly state timeout/failure behavior, but the timeout_ms and poll_interval_ms parameters largely fill that 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?

Schema description coverage is 100%, so the schema already documents all 7 parameters, including the enum for condition and defaults for threshold, timeout, and poll interval. The description restates condition categories but adds little per-parameter meaning, so 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?

States a specific action ('Poll and wait') on a specific resource ('entity reaching spatial state') and enumerates the four condition types. This clearly differentiates it from one-shot sibling tools like query_entities or get_spatial_map.

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 'Poll and wait until' phrasing makes the blocking use case explicit: use this when the caller must wait for a condition to become true, rather than perform a one-shot read. It does not explicitly name alternatives, but the polling semantics provide clear contextual guidance.

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