call_api_operation

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

With no annotations provided, the description carries the burden and does well: it discloses input validation against the OpenAPI spec, the read/write execution split, the server-side env-flag gate, and the human-approval requirement for mutations. It stops short of saying whether writes are reversible, how failures surface, or how list responses are shaped/truncated.

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 short sentences with the core contract first, then the validation guarantee, then the read/write gating. Nothing is padded and no sentence could be dropped without losing a constraint an agent needs.

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 six-parameter nested-object dispatcher with no annotations and no output schema, the critical call-time facts (identifier source, spec validation, write gating, approval) are all present. Remaining gaps are response shape and error behavior, which matter less here because the payload is dictated by the underlying vManage operation rather than by this 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 coverage is 100%, so the schema alone justifies a 3; the description earns the bump by framing body/query/path_params as spec-validated inputs that must be looked up via describe_api_operation, and by tying operation_id to search_api_operations. The confirm semantics it states largely restate the schema text, and max_items is left to 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?

Opens with a specific verb+resource ("Call any vManage API operation by operation_id") and immediately distinguishes itself from the discovery siblings by naming the identifier it consumes, which the schema ties back to search_api_operations. An agent can tell this is the execution endpoint of the search/describe/call triad 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?

Clearly separates the read path (runs directly) from the write path (needs VMANAGE_ALLOW_WRITE=true plus confirm: true after user approval), which is exactly the precondition an agent must check before calling. The gap is that it never addresses when to prefer this generic dispatcher over the dozens of typed siblings like get_bgp_neighbors or get_omp_routes, leaving the main routing decision unstated.

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