IvedaAI: Gateway

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

Annotations are sparse (readOnlyHint: false, destructiveHint: false), so description carries the burden. It does add context about response JSON fields ('status', 'truncated', 'timedOut'), which is useful. Yet it doesn't disclose authentication requirements, side effects of POST/PUT, or error behavior beyond the status field.

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 clear opening, then each endpoint listed with method, path, and parameters. Every line provides specific technical information without fluff or redundancy.

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 four operations, no output schema, and sparse annotations, the description gives a solid overview including endpoint paths, required parameters, and response quirks. However, it lacks authentication notes and does not explain the overall purpose of gateways in the system, which would be helpful for an agent deciding to use 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?

The input schema only has generic properties (body, path, query, operation) with 100% coverage, but those descriptions are minimal. The tool description adds significant meaning by enumerating query parameters for the list endpoint, required fields for create/update, and path parameter for the camera list endpoint. It also references ivedaai_get_schema for full fields, which helps.

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 it covers 'Gateway operations' and lists four specific endpoints with verbs: List, Create, Update, and List Cameras. This distinguishes it from sibling tools focused on other resources like cameras, alerts, or accounts.

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 provides clear context for gateway-related operations and enumerates available endpoints. However, it doesn't explicitly mention when to choose this tool over alternatives (e.g., using ivedaai_camera for camera-specific tasks), so it lacks explicit exclusion guidance.

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