Recurring Skill Gaps

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: ranking semantics, exclusion of mirror_wording hygiene gaps and why (full keyword credit means no score movement), and guidance that raw keys (dual_place, missing_skills, tier values) are internal with category_label as the user-facing wording.

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 core definition is front-loaded in the first clause and the following sentences are dense with interpretation-relevant guidance rather than filler. It runs long, and the internal-identifier aside is somewhat discursive, but each part earns its place by preventing misreading of the output.

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?

With no output schema, the description must convey the return shape, and it does: each row carries category_label and ranking by job demand plus potential match-score gain. Filtering behavior is sketched but not specified in detail, which is the main remaining gap.

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 carries the full parameter burden. Its single line 'Optionally filtered by role/level/type; limit caps the number of skills returned' maps all four schema params to plain words, but supplies no value formats, allowed values, or defaults for level, role_category, employment_type, or limit.

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?

States a specific resource and scope: skills recurring as gaps across saved JDs, measured on best-scoring base resume vs JD before tailoring, ranked by job count and potential match-score gain. It clearly disambiguates from a 'you lack this / learn-next' interpretation. It does not name sibling analytics tools (explore_top_skills, explore_skill_heatmap, resolve_gaps) by name, so sibling differentiation is partial.

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?

Explains what this output represents and explicitly redirects the learn-vs-move question to another surface ('the learn-vs-move distinction is the per-skill tier on build_areas ... get_job_search_brief carries build_areas'). That is a concrete when-to-use-something-else pointer, though it never states a positive trigger condition for calling this tool.

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