jiji_account_data

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

The annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false) already establish the safety profile, so the description's added value is the explicit security boundary: "Never requests passwords, session credentials or bulk seller contacts" – genuinely useful context for a tool enumerating 70+ account resources. It doesn't add anything about pagination, rate limits, or whether different resources return different shapes, though the presence of jiji_next_page makes pagination behavior a meaningful omission.

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?

Two sentences with the purpose front-loaded, followed by the capabilities pointer and a safety guarantee. The resource list is long, but it earns its space by covering the ~70 enum values and giving the agent a mental map of the tool's breadth.

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 output schema and annotations relieve the description of explaining return values and safety, and the one genuinely missing piece – per-resource parameter schemas for a 70+ enum dispatch tool – is explicitly routed to jiji_capabilities. Remaining gaps (pagination handling, sibling overlap) are secondary but keep it short of a 5.

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 carry parameter meaning, and it does partially: it groups the enum values into semantic categories and delegates the exact schemas to jiji_capabilities, which tells the agent precisely where to look. However, the free-form `parameters` object – the hardest part of the schema – is never explained beyond that pointer, so the agent still doesn't know how to populate it without an extra tool call.

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 verb-plus-resource ("Read a mapped Jiji resource") is specific, and the category enumeration (adverts/forms, favourites/searches, profile/settings, chats/media, orders/tracking, balance) makes the tool's scope concrete. It never names overlapping siblings, however, even though the enum includes resources like saved_adverts and chat_rooms that collide with jiji_saved_listings and jiji_list_conversations, leaving the agent to infer which tool wins.

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?

"Use capabilities to discover each exact parameter schema" is useful dependency guidance and the resource taxonomy implies the account-data context, but there is no explicit when-to-use/when-not statement and no routing to or away from overlapping siblings such as jiji_saved_listings, jiji_list_conversations or jiji_next_page. The agent must infer the tool boundary rather than being told it.

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