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

With no annotations, the description carries the full burden; 'Fixed JSON GET' does correctly signal a read-only retrieval, and 'explicit company required' usefully warns that no default company context is assumed. It says nothing about pagination, rate limits, or result size, which for a list endpoint is a real but not fatal gap.

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 terse fragments with no filler, and the endpoint/company constraint is front-loaded. It is telegraphic to the point of terseness, but every fragment carries information.

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?

An output schema exists, so return values needn't be explained, and only two parameters are involved. Still, the opaque 'query' object with zero schema documentation and no annotations leaves the agent dependent on a separate describe call to actually use it.

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 0%, so the description must compensate. It partially does: 'flat query fields' characterizes the opaque untyped 'query' object as free-form filter fields, and it flags company_name as mandatory, with a pointer to describe_nextesy_operation. It stops short of giving any filter keys or syntax.

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 endpoint path ('GET /api/v1/accounting/bookings/recurring-series') conveys that this retrieves recurring booking series, but the description never states the purpose in prose with a verb+resource. It also does no differentiation from siblings like list_booking_templates or list_accounting_booking_rules, leaving the tool name to do the semantic work.

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?

'Explicit company required' gives a prerequisite, and 'see describe_nextesy_operation for filters' routes the agent to the right place for filter discovery. However, there is no statement of when to pick this over the many sibling list_* tools, so usage is only implied.

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