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

The description discloses key behavioral traits: it is a patch operation (partial update rather than wholesale replacement), it modifies the connected account, it requires jobs:apply permission, and it syncs to the cloud for worklittle.com. These traits go beyond the annotations, which only indicate not read-only, not open-world, and not destructive. No contradiction with annotations; readOnlyHint=false correctly permits the write operation.

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?

Four sentences, each earning its place. The core action is front-loaded, followed by usage context, permission requirement, and sync behavior. No redundancy or filler. The field list is condensed into parenthetical categories rather than 20 separate tokens, and the 'Jobs —' prefix is useful context.

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 tool has 20 optional parameters with poor schema-level descriptions, so the description carries a heavy burden. It gives usage context and discloses the patch/sync nature, but it omits critical facts such as how to clear fields (despite schema hints), what happens to unspecified fields, and exact meaning of ambiguous params like 'you_work' or 'phone_national'. The presence of an output schema reduces the need to explain return values, but overall the context is not fully complete for correct invocation.

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 only 15%, so the description must compensate. It does add high-level grouping of the many parameters into categories (name, school, desired role, phone, links, etc.), which gives rough meaning to otherwise bare string fields. However, it fails to map which exact parameter corresponds to each category (e.g., which field is 'desired role'), and does not explain details like clearing via empty strings or the profile_clear_fields array. Combined with self-explanatory names, this is adequate but leaves ambiguity.

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 ('Patch') and a clear resource ('the connected account's Settings profile fields'), then enumerates the categories of fields (name, school, desired role, phone, links, work authorization, driver's license, interests). It is explicitly scoped to Job Cards You overlay, distinguishing it from siblings like get_account (read-only), upload_resume, or apply_for_job. This unambiguously identifies the tool's function.

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 clear context for use: it is called when patching the connected account's Settings profile and is tied to a specific feature (Job Cards You overlay). It also states the required permission (jobs:apply). It does not explicitly exclude alternative tools, but because it is the only account-update tool among siblings and the action is well-defined, an agent can infer the appropriate scenario.

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