kronos_get_custom_fields

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

The annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and purpose but doesn't add significant behavioral context beyond that, such as pagination or response format details. Given the annotations carry most of the burden, a 3 is appropriate for the additional context about usage dependency.

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 concise and front-loaded with the purpose and endpoint, then immediately gives usage guidance. The Args and Returns sections are minimal but clear. It avoids unnecessary verbosity, though the Args section could be redundant with the schema, but it's still compact.

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?

The tool is a simple read operation with only two parameters, and the description covers its purpose, endpoint, and usage dependency. The output schema exists (though not shown in detail), so return value explanation isn't needed. The description omits potential edge cases like error handling or authentication, but for a straightforward read tool with clear annotations, it's sufficiently complete.

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 description coverage is 0%, so the description must compensate. The description mentions 'filial_id, account_id (обязательны)' but provides no further explanation beyond what the schema already has, which itself has detailed property descriptions. The description doesn't add additional meaning or context beyond listing the parameters, so it's baseline adequate but not rich.

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 clearly states the tool 'Получить список пользовательских полей записи' (get list of custom fields) with a specific resource and endpoint (GET /api/v1/custom-fields/{accountId}). It also differentiates from siblings by explicitly mentioning it's needed to learn real ids and types before passing custom_fields to kronos_create_event/kronos_update_event, which sets it apart from other read tools.

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?

The description explicitly says when to use this tool: 'Нужно, чтобы узнать реальные id и типы кастомных полей перед тем как передавать custom_fields в kronos_create_event / kronos_update_event' (Need to know real ids and types before passing custom_fields to create/update event). It also names the specific sibling tools that depend on this information, providing clear context for when this tool is appropriate.

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