FinancesV0_listFinancialEventsByOrderId

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

With no annotations, the description carries the full burden of behavioral disclosure. It vaguely notes 'Runs in your Kuudo deployment, not here' and 'Catalog entry,' but does not clarify whether the tool is actually callable, whether it is read-only, or what constraints apply. The 'not here' remark creates ambiguity rather than resolving it.

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 and somewhat front-loaded, but the opening fragments 'Catalog entry. Runs in your Kuudo deployment, not here' are cryptic and consume space without adding clear operational value. The substantive statement is only the final clause.

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 that needs an order reference, lacks an output schema, and has no annotations, the description is incomplete: no parameter guidance, no return details, and no pagination or scoping information. The only useful context is that it returns financial events per order.

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 has zero properties, so the description's mention of a 'specified order' hints that a parameter should exist but does not name or format it. With additionalProperties allowed, the agent is left to infer the orderId parameter from the tool name rather than from the description.

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 clear action and resource: 'Returns all financial events for the specified order.' The byOrderId scope distinguishes it from group-level or transaction-list siblings, though it does not explicitly name them.

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 select this tool over the many sibling financial-event tools, and there are no exclusions or prerequisites. The only implied usage is for retrieving financial events tied to a specific order.

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