manage_spatial_spec

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.