add_crossing_point

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

With no annotations provided, the description carries the full burden. It discloses the side effect (adds crossing points), the return value (confirmation message with IDs), and the mutual exclusivity of single vs batch modes. However, it omits edge-case behaviors such as duplicate handling, validation errors, or whether batch operations are atomic, leaving some behavioral uncertainty.

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 organized and starts with a clear overview, but it includes an Args section that duplicates parameter descriptions already present in the schema. This redundancy adds verbosity without new value. The core content is concise, but the overall structure could be tighter.

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 presence of an output schema and full schema coverage, the description adequately covers the main usage patterns and return behavior. However, it omits contextual prerequisites (e.g., existence of trust zones) and error-handling behavior, making it only partially complete for a user unfamiliar with the domain. It is adequate but not comprehensive.

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 already provides descriptions for all 6 parameters (100% coverage), including the nuance that items ignores individual parameters. The description's Args section largely repeats the schema, adding only a high-level usage summary. Since schema coverage is high, the description adds minimal value beyond 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 'Add a new crossing point' and then elaborates 'This tool adds one or more crossing points between trust zones in the system architecture.' This identifies the specific create operation and distinguishes it from sibling tools like update_crossing_point and delete_crossing_point. The batch capability adds further specificity.

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

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

The description explicitly explains two usage modes: single item (provide source_zone_id, destination_zone_id, and optional fields directly) and batch (provide items list). It also notes that when items is provided, individual parameters are ignored. This provides clear context, though it doesn't mention explicit when-not-to-use scenarios or alternative tool names.

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