VendorDirectFulfillmentShippingV1_getCustomerInvoices

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

No annotations exist, so the description carries the full burden. It discloses the read-like nature (returns a list) and time-frame filtering, which helps an agent. However, the claim that it 'runs in your Kuudo deployment, not here' is cryptic behavioral information—it neither explains what a catalog entry is nor whether invocation is actually supported.

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 short, but two of its three sentences ('Catalog entry. Runs in your Kuudo deployment, not here.') are cryptic filler that occupies the front-loaded position, while the one informative sentence comes last. Concise in length but wasteful in content allocation.

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 no output schema, no annotations, an empty input schema, and 39 siblings including a same-named tool in the 20211228 API version, the description leaves critical gaps: it doesn't disambiguate the version, name the time-frame parameters, or describe what the returned invoice list contains. An agent could not confidently construct and issue this call correctly from the given information.

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 schema is effectively empty (additionalProperties: true), so no parameter names or formats are documented. The description adds the semantic hint that a 'time frame that you specify' must be provided, but it never names the parameters (e.g., startDate/endDate) or their format. With zero documented params the baseline is 4, but the additionalProperties:true schema plus unnamed required inputs drops it to 3.

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 final sentence clearly states the function: returns a list of customer invoices for a user-specified time frame, with a specific verb and resource. The word 'list' helps distinguish it from the sibling getCustomerInvoice (singular). However, the opening 'Catalog entry. Runs in your Kuudo deployment, not here' muddies whether the tool is actually callable from this environment.

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?

No guidance is given on when to use this tool versus siblings such as VendorDirectFulfillmentShipping20211228_getCustomerInvoices or the singular getCustomerInvoice. No alternatives are named and no exclusions or conditions are stated. The only implied usage signal is that an invoice list is needed for a time frame, which is weak comparative guidance.

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