ncloud_sens_list_brandmessage_requests

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

Goes well beyond the single readOnlyHint annotation by disclosing a genuinely surprising behavior: 'An empty HTTP 404 reply means no matching records (observed live with an unknown requestId).' This prevents an agent from misdiagnosing a 404 as an endpoint failure, and the time-window constraints are behavioral limitations an agent must respect. No contradiction with 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?

Three sentences each earn their place: the action+endpoint, the required selector constraints, and the 404 edge case. The verb is front-loaded and the total is roughly 45 words for a 14-parameter tool. The 'observed live' parenthetical adds practical credibility without bloat.

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 complex tool with 14 parameters, zero required fields, conditional requirements, and no output schema, the description covers the essentials: what it does, all valid filter modes, companion-parameter rules, and the non-obvious 404 semantics. Minor gaps: it doesn't clarify how the additive filters (messageId, to, templateCode, statuses) combine with the three selector modes, nor mention pagination iteration with nextToken — leaving an agent to infer those interactions from the schema.

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 baseline is 3. The description earns a 4 by synthesizing cross-parameter constraints that individual field descriptions only hint at: which selectors are mutually exclusive, the ≤31-day vs ≤24h windows, and the plusFriendId-unless-requestId rule. It organizes 14 loose parameters into a small number of valid call patterns.

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?

States a specific verb ('List') + resource ('Brand Message delivery requests') plus the exact HTTP endpoint, which distinguishes it from siblings like ncloud_sens_send_brandmessage (send vs list), ncloud_sens_get_brandmessage_status (status of one vs list of requests), and ncloud_sens_list_brandmessage_templates/images (different resources). An agent can select it correctly from the large sibling set without opening the 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?

Provides exceptionally clear usage context: the three mutually-exclusive selection modes (requestId, or requestStartTime+requestEndTime ≤31 days, or completeStartTime+completeEndTime ≤24h) and the plusFriendId dependency. What it lacks is explicit routing against alternatives — it never says 'use get_brandmessage_status for a single message status' — so no exclusions are stated, though the tool name and resource description make the intended use unambiguous.

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