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

With annotations already declaring readOnlyHint=false, destructiveHint=false and idempotentHint=false, the description adds real context: it hashes rather than mutates, produces an immutable artifact, and discloses the return shape. It does not address the non-idempotent implication (repeat calls yielding distinct packs), which is the one behavioral gap left to 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 core purpose and return shape are front-loaded and the text is dense with little waste. The final sentence restates 'immutable cryptographic' and repeats the tool's own name, which is slight redundancy but it carries the sibling differentiation.

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 exists, but the description supplies the return shape ({ok, pack_id, hash, payload}), which covers the main informational gap. For a 7-parameter, nested-object, zero-required tool it is nearly complete, though it never explains what happens when the optional ID sets are omitted.

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 seven parameters, including the nested linked_state_memory_nodes object. The description maps its prose ('entity positions, observation reconciliations, snapshot states') onto some of those inputs but adds no format, ordering, or requiredness guidance 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?

Specific verb ('package') plus named resources (entity positions, observation reconciliations, snapshot states) and a declared output artifact (immutable SHA-256 hashed evidence pack). It also distinguishes itself from the sibling manage_snapshot by scope, so an agent can separate the two without opening either 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?

Explicitly states the selection rule against an alternative: use this instead of manage_snapshot when producing immutable cryptographic verification packages rather than database checkpoints. It also clarifies the non-mutation boundary ('does not change entities; hashes current proof').

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 readOnly/idempotent/non-destructive, but the description adds real context beyond them: it clarifies that 'read-only' here means the tool generates Playwright inputs and 'does not press keys', and it states the return shape ({ok, action, inputs[]|screen_coords|ray}). It omits rate limits, auth requirements, or failure modes, so it stops short of full 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?

Four sentences, front-loaded with the core purpose and backed by the action list, return shape, and sibling routing. The 'Read-only: generates Playwright inputs, does not press keys' clause partially restates the readOnlyHint annotation, a minor redundancy, but overall there is little 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?

For a 17-parameter, nested-object tool with no output schema, the description compensates by stating the return shape and the three action modes, which is what an agent needs to call it correctly. It is nearly complete, though the absence of guidance on which parameter groups pair with which action leaves some inference to the caller.

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 in the schema with defaults and enums. The description adds only indirect meaning (naming the action enum values and the WASD/click-to-move schemes); it does not explain how camera, viewport, or control_profile interact for a given action, 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?

The description gives a specific verb+resource ('Translate 3D navigation paths into Playwright commands'), enumerates the three concrete actions (generate_inputs, project_screen, unproject_ray), and explicitly routes the agent away from the sibling simulate_movement. An agent can identify the tool's scope without opening 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?

It explicitly names the alternative (simulate_movement) and the condition that selects this tool instead ('when translating 3D trajectories into Playwright browser automation commands'), which is strong routing guidance. However, it offers no when-to-use discrimination among its own three actions (e.g. project_screen vs unproject_ray, or when click-to-move beats WASD), so guidance is clear but partial.

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 annotations already establish that this is read-only, idempotent, and non-destructive, and the description reinforces that it does not write entities. It adds useful behavioral context beyond the annotations by naming the occlusion method (ray-AABB) and the return structure. It stops short of describing edge cases or performance characteristics, so it is strong but not exhaustive.

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

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

The description is short and front-loads the computation and its scope. However, 'Read-only. Does not write entities.' is redundant with each other and largely duplicates the annotation-style safety information, slightly reducing efficiency.

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

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

Although there is no output schema, the description supplies the return shape as {visible[], occluded[], observer}, and it covers the core behavior, occlusion method, and sibling alternative. Together with the fully documented input schema and annotations, an agent has enough context to invoke 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%, so the schema already documents all five parameters, including defaults for fov_degrees and max_distance. The description does not add syntax, constraints, or meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific computation: which entities should be visible from an observer pose and FOV cone, including ray-AABB occlusion. It distinguishes this tool from the sibling get_spatial_map by contrasting filtered visibility/occlusion with unfiltered world states.

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 explicitly says to use this tool instead of get_spatial_map when the task is computing observer FOV visibility and occlusion cones rather than unfiltered world states. The condition for choosing this tool over the named alternative 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: it is a snapshot of current SQLite state, explicitly 'not a live renderer,' and the payload is returned in the requested format. It stops short of noting snapshot staleness timing or size limits, hence not a 5.

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

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

Front-loaded with purpose and the format list, then filters, then the routing rule. Efficient overall, though the long inline enumeration of nine formats partially duplicates the schema enum and makes the opening sentence dense.

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 7-parameter, multi-format export tool with no output schema, the description covers what is produced, the read-only snapshot nature, and the key filters. It does not explain what the non-obvious formats (spatial_vlm, joint, compact_slice) contain, leaving some format choices under-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?

Schema description coverage is 100%, so the baseline is 3. The description re-states region_id and min_confidence as optional filters and mentions the format enum, but adds no syntax, defaults, or interaction detail beyond what the schema descriptions already provide.

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?

Specific verb+resource: 'Export the known world' with the full set of supported formats enumerated, and it explicitly distinguishes itself from the sibling query_entities. An agent can tell what it produces and when it differs from the filtering tool without opening 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?

States the alternative by name and the condition that selects it: 'Use get_spatial_map instead of query_entities when exporting full environment snapshots or 3D meshes rather than filtering entities.' This is an explicit when-to-use / when-not-to-use routing rule.

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 may create or update entities (a write operation) when reconcile=true, it re-identifies by Euclidean proximity, boosts confidence, and optionally reconciles against the expected frustum. It also returns a specific shape {ok, matched[], created[], lost[], reconcile}. Annotations already flag readOnlyHint=false, so the description adds useful context about what actually happens (merge, re-identify, confidence boost). Doesn't mention idempotency or failure modes, hence a 4 not 5.

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 the core action, then behavioral details, then a usage-routing sentence. Efficient and well-structured, though the return shape list and the phrase 'This is the perception writer' could be trimmed without loss. Every sentence carries some value, but not maximally tight.

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 6-parameter mutation tool with no output schema, the description does a good job covering what the tool does, its write behavior, and its return shape. It explains the reconcile option's effect and routes the agent away from update_entity. Missing: what happens when no match is found (created vs lost semantics), and any mention of required permissions or failure modes. Given annotations cover safety, this is nearly 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 83%, so the schema already documents most parameters thoroughly (project, reconcile, detections with nested fields, observer_pose, visual_state_id). The description adds meaning for reconcile ('reconcile against the expected frustum') and explains the merge logic but doesn't add syntax or format beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 verb+resource ('Merge vision detections into the world model') and explicitly distinguishes from the sibling update_entity ('use ingest_observation instead of update_entity when merging camera or sensor perception detections'). This is a clear purpose with sibling differentiation. However, the title is null and some phrasing like 'perception writer' is jargon-adjacent rather than precise.

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 a clear condition for choosing this tool over the sibling update_entity (merging camera/sensor detections vs manual authoring). The reconcile parameter's behavioral trigger is also stated ('optionally reconcile against the expected frustum'). However, no exclusions or prerequisites are given, and it doesn't address when to use it vs. recording outcomes or querying entities.

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 annotations already covering readOnlyHint=false, destructiveHint=false, and idempotentHint=false, the description adds useful behavioral detail: link/unlink mutate association rows only, get_context is read-only, and it specifies the return shape. This clarifies the mixed read/write nature of the tool 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 front-loaded with the core purpose and action variants, then adds mutation scope, return shape, and the sibling alternative. Every sentence contributes useful selection or invocation information without unnecessary padding.

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 complex 13-parameter tool with nested objects and no output schema, the description supplies the key missing context: action behavior, read-only vs mutating distinctions, return shape, and the sibling alternative. It does not explain every parameter interaction, but the exhaustive schema descriptions carry that load.

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 input schema already documents all 13 parameters, including enums and nested objects. The description repeats the action values and return shape but does not add parameter-level meaning beyond the schema, making the baseline 3 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 states specific verbs and resources: linking/unlinking entities and regions to state-memory task nodes, plus extracting a goal-relevant spatial slice. It names the action variants and explicitly distinguishes itself from record_outcome, so an agent can route to it without opening 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?

It gives a clear alternative: use link_to_goal instead of record_outcome when associating entities with state-memory task nodes rather than recording physical movement deltas. However, it does not address when to prefer get_context over neighbouring read tools such as query_entities or get_spatial_map.

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?

Goes well beyond the annotations by disclosing per-action behavior: restore overwrites live state, undo reverts the last matching mutation, and both are 'not always reversible except by saving first,' while diff/list/history/time_travel are read-only. The annotations only give tool-level destructive/idempotent hints; the description gives action-level detail that is exactly what an agent needs to avoid data loss.

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 the verb set, then actions, then safety warnings, then return shape, then sibling routing — every sentence carries distinct information with no padding.

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 7-action tool with no output schema and no required params, the description supplies the action taxonomy, destructive/read-only classification, return envelope ({ok, action, snapshots[]|diff|state}), and routing versus siblings. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds action semantics and defaults ('type' is the mutation type to undo, default any) and maps parameters to actions (name for save/restore, timestamp for reconstruction). It adds meaning beyond the field-level descriptions without fully restating them.

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?

Opens with a specific verb set ('Checkpoint, diff, undo, or time-travel') and resource ('spatial world database'), then enumerates the exact action enum. It explicitly distinguishes itself from the sibling update_entity, so an agent can route without opening either 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?

States when to use it versus a named alternative: 'Use manage_snapshot instead of update_entity when rolling back, diffing, or time-traveling database state rather than editing single entities.' It also flags which actions are destructive, giving both when-to-use and when-to-be-careful guidance.

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

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

Annotations are tool-level (readOnlyHint=false, destructiveHint=false, idempotentHint=false) and the description adds the crucial per-action nuance that verify is read-only while set persists constraints. It also discloses the return shape {ok, action, spec_id, passed, violations[]} in the absence of an output schema. It stops short of covering overwrite/idempotency behavior for repeated 'set' calls or any permission requirements.

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 the resource and action list, then mutation semantics, return shape, and the sibling disambiguation — every sentence carries distinct information with 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?

For an 8-parameter, nested-object tool with no output schema, the description covers action set, mutation semantics, return shape, and routing to the right sibling. Gaps remain around re-set/idempotency behavior and the meaning of the 'custom' constraint and 'tolerance' percentage.

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 3; the description adds value by tying parameters to actions (constraints and baseline registration belong to 'set', live-entity evaluation belongs to 'verify'). It does not explain tolerance semantics, the 'custom' constraint type, or which params each action requires, so it stays just above 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?

States a specific resource (Spatial SDD physical baseline contracts) and enumerates the three concrete actions with one-line semantics for each, so an agent knows exactly what the tool does. It also names the sibling it should not be confused with (update_entity), making it distinguishable without opening either 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?

Provides an explicit routing rule: 'Use manage_spatial_spec instead of update_entity when validating physical contract baselines rather than mutating live entity state.' It also disambiguates the internal actions (verify is non-mutating, set persists), giving both when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description reinforces 'Read-only' and adds the return envelope {ok, count, entities[]} plus the dual-mode behavior (search vs direct entity_id lookup with history). It doesn't mention pagination or cost limits, but the added context is meaningful.

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 the primary search purpose, then the alternate mode and return shape, then the sibling routing. Three dense sentences with no filler, though it is slightly packed for a single paragraph.

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, zero-required read tool with no output schema, the description supplies the return shape, the two invocation modes, and the sibling boundary. An agent has enough to select it and choose the right parameter family.

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 one of the 13 parameters is already documented in the schema; the description only paraphrases the filter categories. No syntax, format, or interaction details (e.g., include_history requiring entity_id) are added beyond what the schema states, so the baseline 3 applies.

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

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

States a precise verb (find entities) plus the full set of filter dimensions (keyword/FTS5, type, region, proximity, tags, status) and a distinct alternate mode via entity_id. It explicitly differentiates itself from the sibling get_spatial_map by scope (subset search vs full topology export).

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?

Names the alternative tool and the condition selecting it ('Use query_entities instead of get_spatial_map when searching for specific subsets rather than exporting the full topology'), and explains the second usage mode (entity_id for single-entity lookup and trajectory). Both when-to-use paths are 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?

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's main added value is the return shape ({ok, action, success:boolean}) and the 60Hz off-tick spool ingestion mode, both of which are useful. However, the claim that the tool records 'entity destruction' sits in tension with destructiveHint=false, and the description does not clarify idempotency or what happens on repeated ingestion of the same spool batch — a real gap given idempotentHint=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?

Four tight sentences, front-loaded with the primary capability before exclusions and alternatives. It is dense but every clause carries routing or return-value information; no filler 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?

With no output schema, the description usefully supplies the return shape, and it covers both the single-record and batch-spool modes despite 13 parameters and 0 required fields. It could be more explicit about what happens if neither entity_id nor items is supplied, but overall it is complete enough to invoke correctly.

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

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

Schema description coverage is 100% across 13 parameters, so the baseline is 3 and the schema already documents enum values ('record' default, 'from_tick' batch) and the batch alias. The description adds little beyond that, and its instruction to mark destruction 'via status: "destroyed"' does not match the actual boolean `destroyed` parameter, which is a minor but real inaccuracy.

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 verb (record) and enumerates the exact resource types handled: action execution results, movement deltas, property changes, entity destruction, and 60Hz spool ingestion. It actively distinguishes itself from siblings by ruling out vision ingest and manual pose edits and by contrasting with 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?

It gives explicit when-not guidance ('Not for vision ingest or manual pose edits') and names the alternative with the selecting condition ('Use record_outcome instead of update_entity when applying executed action results and status deltas rather than hand-authoring entities'). Nothing about tool selection is left 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=false, idempotentHint=false, destructiveHint=false. The description adds real value beyond that: it clarifies that only the relation graph is mutated (not entity poses) and states the return shape {ok, relation}. It does not discuss idempotency semantics of add-vs-remove, but the scope clarification is substantive.

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 and scope, then usage routing. The inline enumeration of all 13 relation values duplicates the schema enum, which is mild waste, but the rest is tight and each 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?

For a 9-param mutation tool with nested objects and no output schema, the description covers mutation scope, return shape, and alternative selection well. Undocumented areas (bidirectional auto-inverse, offset semantics) are fully described in the schema, so nothing critical is missing.

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 9 params. The description largely repeats the action and relation enums already present in the schema and adds no meaning for offset, distance, bidirectional, or metadata. Baseline 3 applies.

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

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

States a specific verb pair (record/remove) and resource (spatial relationship between two entities), and immediately contrasts with update_entity. An agent can distinguish it from siblings without opening 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?

Explicitly routes the agent: 'Use set_relation instead of update_entity when establishing topological links (on, inside, contains) rather than setting entity coordinates.' It names the alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description is consistent ('Read-only simulation'). It adds value by disclosing the return shape {ok, is_valid, destination, collisions[], waypoints[]}, which is otherwise unavailable since there is no output schema. It stops short of noting side effects or failure behaviors.

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 tight sentences, front-loaded with capabilities and ending with the sibling routing rule. The inline return-shape object is dense but earns its place given no output schema exists.

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 11-parameter, zero-required tool with modes and no output schema, the description supplies the mode semantics and return keys an agent needs. It does not explain which parameters pair with which mode, leaving that inference to the schema's own descriptions.

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 all 11 parameters are already documented, including mode-dependent fields. The description's mode list adds light routing help, but it largely restates the enum in the schema, so baseline 3 applies.

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

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

States three specific capabilities (predict trajectory, test AABB collisions, compute navigation waypoints) with the exact mode names that trigger each, so an agent can map intent to mode without opening the schema. It also explicitly separates itself from record_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?

Gives an explicit when-to-use rule and names the alternative: prefer this over record_outcome for hypothetical motion/collision testing before executing an action. This is the exact routing information an agent needs.

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 only declare the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), yet the description adds the semantics that actually matter: this is a partial merge that preserves omitted fields rather than a full replace, ids are ULID-assigned on create, status defaults to active, and it does not ingest vision detections or apply action results. With no output schema present, it also supplies the return shape {ok, entity_id, created, entity}.

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 the core verb and merge rule, and nearly every clause carries information. There is mild redundancy: 'Manual authoring only' and 'Does not ingest vision detections' partially overlap with the closing sentence routing to ingest_observation, which could be tightened to one statement.

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 15-parameter tool with nested objects and no output schema, the description covers everything an agent needs: creation vs update branching, merge vs replace semantics, defaults, the confidence scale, what the tool deliberately does not do, and the response payload. No material gap remains.

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 already 100%, so the baseline is 3. The description goes beyond it by explaining id's dual role (create vs update), the ULID auto-assignment behavior, the 0.0–1.0 object-permanence meaning of confidence, and the active default for status — semantics the schema states only as types and defaults.

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?

Opens with a specific verb pair and resource: 'Create or upsert one spatial entity', then enumerates the payload domains (position, orientation, AABB, tags, properties, confidence). It explicitly contrasts itself with the sibling ingest_observation, so an agent can route without opening either 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?

Gives concrete when-to-use rules keyed on the id parameter ('Omit id to create', 'Provide id to update'), states the scope constraint ('Manual authoring only'), and names the alternative with the discriminating condition versus ingest_observation. Nothing is left 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?

Beyond the annotations (destructive/highlight non-idempotent writes), the description discloses real behavioral traits: lease acquire fails if the resource is held, set accepts a payload with coordinates plus optional ttl_seconds, and the return shape is {ok, action, items[]|entry|lease}. It does not add detail about permission requirements or what specifically is destroyed on delete, but the added failure-mode and TTL context is substantive.

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 purpose and the sibling routing rule are front-loaded, which is good, but the inline enumeration of all nine action values restates the schema enum and consumes space without adding information. It is compact for a 15-parameter tool yet contains some redundant 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 complex multi-action tool with 15 parameters and no output schema, the description supplies the missing return shape plus the key failure and TTL semantics, which is more than most. It still omits prerequisites, defaults (beyond the schema's), and richer lease-conflict behavior, so it is strong but not exhaustive.

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 15 documented parameters, so the baseline is 3 per the rubric. The description adds meaning for a few fields (payload/coordinates, ttl_seconds, lease acquire-vs-release behavior) but is silent on many others such as intention_id, topic_prefix, include_expired, limit, and sender/agent_id, so it does not exceed 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 domain (multi-agent spatial coordination: topics, collision alerts, mutex region leases) and enumerates the supported actions, so an agent knows what the tool manipulates. It also explicitly separates itself from set_relation. The only weakness is that the many-action surface makes the core purpose slightly diffuse.

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 gives an explicit routing rule: use this instead of set_relation when coordinating transient multi-agent collision alerts and mutex region leases, which implicitly tells the agent when not to use it (persistent relations). However, it only contrasts against one of fifteen siblings and offers no broader context on when a blackboard is preferable to other coordination 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds real behavioral context: it blocks/polls, states the default timeout and poll cadence, and gives the timeout failure shape ({ok:false, timeout:true}). However it states poll_interval default 500ms while the schema says 250ms, an internal inconsistency that weakens trust in the disclosed defaults.

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 the core verb and condition list, then behavior, then the routing rule to query_entities; every sentence carries information. It loses a point for spending a sentence on defaults already in the schema, one of which contradicts them.

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

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

With no output schema, the description helpfully supplies the return shape and the timeout payload, and covers defaults and blocking behavior for a 7-parameter tool. Remaining gaps are minor: no mention of maximum timeout, cancellation, or what happens to concurrent polls.

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 schema already documents every parameter including defaults, so the baseline is 3. The description's restatement of timeout/interval defaults adds no new meaning and even conflicts with the schema's poll_interval default, while the enum values it paraphrases are already self-describing.

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?

Names a specific verb+resource ('poll and wait until an entity reaches a specific spatial condition') and enumerates the four condition kinds, so the agent knows exactly what is being awaited. It explicitly distinguishes itself from the sibling query_entities, so the tool is separable without opening a 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 final sentence gives an explicit alternative and the selecting condition: use this instead of query_entities when polling asynchronously for a state transition or region entry. Both when-to-use and which-sibling-not-to-use are stated.

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