Shipping_submitNdrFeedback

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

With no annotations, the description carries the transparency burden. It does disclose an important environment trait—that the tool runs in Kuudo rather than here—and implies a write action via 'submits.' However, it omits side effects, eligibility criteria, authorization needs, and response behavior, which leaves meaningful unknowns for a mutation-like API.

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 only three short sentences and contains little filler. The purpose is not front-loaded because 'Catalog entry' comes first, but the overall size is appropriate and the environment caveat is useful enough to justify its place.

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 tool with no annotations and no output schema, this description gives only the basic purpose and runtime environment. It lacks details about required request body, shipment eligibility, expected response, or failure behavior, so an agent could select it confidently but cannot invoke it correctly without additional context.

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 is empty with additionalProperties true, so there are no formal parameter names to document. However, the description does not clarify how to specify the eligible shipment or the NDR feedback payload, making invocation ambiguous despite the schema's permissive additionalProperties flag.

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 states a specific action—submitting NDR Feedback for an eligible shipment—with a clear verb and resource. No sibling tool exists for NDR feedback, so it is easy to distinguish among the large Shipping_ family.

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?

It gives clear context by noting the API 'Runs in your Kuudo deployment, not here,' and limits the action to 'any eligible shipment.' It doesn't list explicit alternates or exclusions, but no sibling tool covers NDR feedback, so the selection guidance is adequate.

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