update_crossing_point

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

With no annotations provided, the description carries the full transparency burden. It discloses that the tool mutates existing crossing points and returns a confirmation message, and it describes batch behavior. However, it omits permission requirements, error cases, reversibility, and effects on related architectural entities, leaving notable gaps for a mutation 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 well-structured with a front-loaded summary, single/batch mode instructions, an Args block, and a return note. It is somewhat redundant—the second sentence paraphrases the first, and the Args block repeats schema content—but it remains scannable and appropriately sized for a 7-parameter tool.

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 full schema coverage, an output schema, and a clear return description, the description is largely complete for invoking the tool. It covers both usage modes and parameter requirements. Some ambiguity remains around precedence when both id and items are provided, and the description mentions a ctx argument not present in the input schema, but the schema itself covers these details.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description reinforces the single-item id requirement and the batch items structure, adding minor mode context, but it largely duplicates the schema's own parameter descriptions without adding significant new meaning.

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 opens with 'Update an existing crossing point,' a specific verb+resource pairing that clearly identifies the tool's function. It also highlights batch support, which distinguishes it from sibling tools like add_crossing_point, list_crossing_points, get_crossing_point, and delete_crossing_point.

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 single-item versus batch usage modes, including the id requirement for single updates and the items structure for batch operations. It does not explicitly mention when not to use this tool in favor of another, but the update-specific context and mode guidance provide sufficient operational clarity.

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