skill_data

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

With no annotations, the description carries the full behavioral disclosure burden. It does so well by revealing an important limitation: '274 of 426 skills carry a real damage coefficient,' warning the agent that some skills will lack this data. It also clarifies that returned damage is a percentage, not an absolute number, which prevents misinterpretation.

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 concise sentences with no filler. The core data content is front-loaded, followed by a useful caveat about coverage, then a direct pointer to the alternative tool. Every sentence earns its place.

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 simple one-parameter lookup with no output schema, the description covers the source, the fields returned, the percentage semantics, the coverage limitation, and the relevant sibling for conversion. It does not describe the exact return shape or how missing coefficients are represented, but those are minor gaps given the tool's simplicity and the fields listed.

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 schema provides only a single required 'skill' string parameter with no description, and schema description coverage is 0%. The tool description names 'skill' but does not specify whether it expects a skill name, ID, or other identifier. Since the parameter name is self-explanatory and there is only one parameter, this is adequate but leaves some ambiguity for an agent.

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 names a specific resource (Skill.data), a precise verb class (returns numeric per-level data), and the exact fields returned: damage % of ATK, targets, duration, effect %. It also distinguishes itself from its sibling skill_damage by noting that this tool returns raw percentages, not actual numbers. An agent can tell this tool apart from related siblings without opening any schemas.

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 gives explicit but partial routing guidance: 'Use skill_damage to turn a % into an actual number.' This tells the agent when to choose skill_damage instead of this tool for damage conversion. It does not enumerate other when-to-use / when-not-to-use cases versus the many sibling data-lookup tools, but it provides enough context for the most likely decision.

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