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

Annotations only indicate readOnlyHint=false and destructiveHint=false. The description goes far beyond that by revealing owner-only restrictions, account-safety implications, clamping to tier-aware ceilings, reset-on-zero semantics, rejection of unknown keys, jitter around the set value, and the exact return shape. This is rich behavioral disclosure.

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 description is dense but every sentence carries essential operational information. It fronts the action and trigger condition, then explains parameter semantics, nuanced jitter behavior, permission requirements, and return value without fluff. The structure with clear paragraphs makes it easy to scan.

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 mutation tool with no output schema, the description is complete: it specifies exactly when to call it, what it does, how the parameter behaves, edge cases, permission restrictions, follow-up verification, and the return format. An agent has everything needed to invoke it correctly and communicate results to the user.

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?

Although the input schema already describes the 'limits' parameter with 100% coverage, the description substantially deepens it: it explains partial-map behavior, that unnamed actions keep their caps, clamping to the ceiling from check_linkedin_daily_usage, 0-or-below reset behavior, and that keys come from configurable_limits. This adds real semantic value beyond the schema.

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 opens with a specific verb and resource: 'Change the user's per-action LinkedIn daily caps', and immediately ties it to a concrete UI context. It clearly distinguishes this from the sibling read-only tool check_linkedin_daily_usage and from the similar set_linkedin_warmup by focusing on daily per-action limits.

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?

Explicit when-to-use guidance is given: 'Call this when the user asks to raise or lower how many connection requests, messages, InMails, etc. they send per day'. It also tells the agent to actually make the change rather than describe the UI, and to re-read check_linkedin_daily_usage afterward to confirm stored caps, providing clear execution guidance.

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