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

Annotations mark this as a non-read-only, non-idempotent write, and the description goes well beyond them: confirm=false writes nothing and returns a preview, confirm=true writes, submissions are reviewed before counting, at most 5 confirmed submissions per 60s, retries reuse the same submissionId, and email verification is needed only when signed out. It also states that nobody replies and that submitting does not end the turn, which no annotation conveys.

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 trigger condition and the confirm/preview protocol are front-loaded, and the paragraphing separates eligibility, gathering procedure, mechanics, and prohibitions sensibly. It is long for a tool description, and the trailing 'REQUIRED arguments' enumeration plus the array-typing note duplicate what the schema already enforces, which costs a point.

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 36-parameter, 10-required mutation tool with no output schema, the description supplies the full workflow: conversational field gathering, slug resolution order, English text fields, the two-call preview/confirm handshake, retry semantics, rate limits, and anonymity behavior. The only thing left implicit is the exact preview payload, which is minor.

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 97%, so the baseline is 3, but the description adds real cross-field semantics: stock options belong in totalOptionsGranted/avgAnnualOptionsGranted with strike and preferred price rather than otherDetails, option prices may use optionPriceCurrency, amounts are in the submission's own currency, and array-typed arguments must be arrays even when singular. That is genuine value beyond the schema, though the enumerated required-argument list largely restates 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?

Opens with a specific verb and resource: 'Add the user's own compensation to Levels.fyi', further narrowed to pay they earn now or an offer they received. It is unambiguously the only write-a-submission tool among siblings that are all read/search tools, so an agent can select it without opening any schema.

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?

Gives an explicit trigger set — 'only when the user is evaluating their compensation, asks to add their pay, or says yes when you offer' — plus a concrete do-not-submit list (another person's pay, estimated numbers, job-posting ranges, hypotheticals, test entries). It also names the prerequisite sibling tools for slug resolution (search-companies, get-job-family, search-locations, get-company-levels, get-vesting-schedules).

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