profile_import_jobkiller

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

With no annotations, the description carries the full behavioral burden, and it does add one genuinely useful trait: the resulting profile 'Leaves verified=false', which tells the agent a follow-up verification step may be needed. It does not disclose whether existing profile data is overwritten or merged, whether the operation is idempotent, or what failures look like for malformed input — significant gaps for a bootstrap/mutation tool.

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 short sentences with the action and accepted sources front-loaded, followed by the post-condition. No filler or repetition; the only minor cost is that the compression contributes to the json_path/.html ambiguity.

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 single-parameter tool with no annotations and no output schema, the description covers the source and one post-condition but omits merge/overwrite semantics, the return value, and how errors surface. Adequate to attempt a call, not complete enough to predict its effect on an existing profile.

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 coverage is 0% and the sole parameter 'json_path' has no description, so the description must compensate, and it only partly does. Worse, it advertises accepting a CV '.html' while the only parameter is named 'json_path', leaving the agent unsure whether HTML files are passed through that same parameter — an ambiguity that could cause an incorrect invocation.

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 uses a specific verb ('Bootstrap the profile') plus named source formats (JobKiller user_info .json / CV .html), which distinguishes an import/bootstrap action from profile_update or profile_add_item. It is clear what the tool does, though it does not explicitly name the sibling it replaces.

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?

Usage context is implied by 'Bootstrap' and the JobKiller-specific source formats, so an agent can infer this is for initial profile population from JobKiller exports rather than incremental edits. However, there is no explicit when-not guidance, no statement about what to do if a profile already exists, and no reference to profile_update as the alternative for subsequent changes.

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