mess_get_registered_extras

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

Annotations already indicate this is a safe, read-only, idempotent, and open-world operation (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true). The description adds minimal behavioral context by specifying it returns 'JSON array of ExtraRegistration objects', but does not detail aspects like error handling, rate limits, or authentication needs beyond the schema. With annotations covering core traits, the description adds some value but not rich behavioral disclosure.

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 structured with a clear purpose statement followed by 'Args:' and 'Returns:' sections, making it easy to parse. It is concise with no wasted sentences, though the parameter listing could be more integrated into the main text. The front-loaded purpose statement earns its place, but minor improvements in flow could enhance readability.

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?

Given the tool's complexity (read-only query with authentication), annotations provide safety and idempotency info, and an output schema exists (implied by 'Returns: JSON array of ExtraRegistration objects'), the description is reasonably complete. It covers purpose, parameters, and return format, though it lacks usage guidelines and detailed behavioral context. The presence of annotations and output schema reduces the burden on the description, making it adequate but not exhaustive.

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%, meaning parameters are undocumented in the schema. The description compensates by listing parameters ('auth_key/session, meal (required), optional date (YYYY-MM-DD)') and clarifying that 'date' defaults to today. However, it does not fully explain parameter semantics, such as the relationship between 'auth_key' and 'session' or the format of 'meal' values. This partial compensation results in a baseline score of 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 description clearly states the tool's purpose: 'Get extra item registrations for the current user for a meal on a date.' It specifies the verb ('Get'), resource ('extra item registrations'), and scope ('current user', 'meal', 'date'), but does not explicitly differentiate it from sibling tools like 'mess_get_extras_in_range' or 'mess_list_extras', which prevents a score of 5.

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 provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'mess_get_extras_in_range' or 'mess_list_extras', nor does it specify prerequisites such as authentication requirements beyond what's implied in the parameters. This lack of contextual guidance limits its utility for an AI agent.

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