Levels.fyi

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.

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

Annotations already cover read-only safety, so the description adds valuable behavioral context: it enumerates free inputs, specifies a 12-month data scope, and clarifies that certain dimensions are not accepted by any tool here. It stops short of describing return format or pagination, but those are less critical for a parameter-free discovery 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?

The description is two sentences, front-loaded with the core purpose, then efficiently packs essential details about free inputs, exclusions, and when to call it. Every sentence earns its place with no redundancy.

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?

Given there is no output schema and no parameters, the description effectively communicates what the tool returns (free input list and non-free dimensions) and the data scope (total compensation from last 12 months). An agent has enough information to call it correctly and interpret the result.

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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and it actually provides useful meta-information about accepted inputs across the toolset, which enhances understanding without being redundant.

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 specifically states the tool lists available inputs and filter values for the free tier, with clear examples of free and non-free dimensions. This distinguishes it from all sibling tools, which either query data or manage entities, by making it an explicit discovery mechanism for accepted parameters.

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?

It explicitly says to call this before building a query if unsure what a tool accepts, which is a clear when-to-use directive. The implication is that it need not be called when the agent already knows accepted inputs, providing adequate when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description carries a lighter burden. It adds real value by enumerating the returned profile fields (compensating for the missing output schema) and by flagging slug as the preferred lookup key. It does not say what happens when the company is not found or when a name matches multiple companies.

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?

Front-loaded with the verb and the return shape, then the routing hint, then the required-argument note. The trailing 'REQUIRED arguments: companyNameOrSlug' is mildly redundant with the schema's required array but does no harm.

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 one-parameter read tool with annotations and no output schema, the definition is nearly complete: it covers purpose, input preference, alternative routing, and the returned field set. The only meaningful gap is error/ambiguity behavior, which an agent would need to guess.

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?

With a single parameter at 100% schema coverage, the baseline is 3, but the description adds genuine semantics: slug is preferred over name, and the argument is marked required. The schema description alone ('Name or slug of a company') conveys none of that preference.

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 verb and resource ('Look up a single company') and enumerates the returned profile fields, so the agent knows exactly what it gets back. The parenthetical '(preferred)' for slug and the reference to search-companies distinguish it from the search siblings.

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?

Explicitly routes the agent: prefer slug over name, and use search-companies first when only a name is available and the exact slug is needed. That names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare this as a safe, read-only, closed-world lookup. The description adds meaningful behavior beyond that: matching is case- and separator-insensitive, unknown groups fall back to listing available groups, and the full set of available group names is disclosed.

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 compact and front-loaded: the core resolve action comes first, followed by matching behavior, fallback behavior, and the available values. Every sentence contributes operational information.

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 read-only lookup with no output schema, the description is complete: it explains the return value, the fallback behavior, case/separator insensitivity, and all available group names. An agent has enough information to call it correctly without further context.

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 100%, so the baseline is 3, but the description adds usable semantics beyond the schema by enumerating all available group names and clarifying the unknown-group fallback. It does not add new syntax detail, so it is slightly above baseline rather than fully exhaustive.

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 states a specific verb and resource: resolve a named company group into company slugs. It also names the downstream use case, the benchmark tools' companySlugs filter, which makes the tool's role distinct from sibling search/get tools.

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?

It explicitly says to omit the group parameter or pass an unknown group to list available groups, and explains that the result is intended for the benchmark tools' companySlugs filter. This gives clear when-to-use and practical routing guidance.

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

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

Annotations already declare readOnly/openWorld/destructive, and the description layers on non-obvious behavior: alternate names are included per level, results are ordered by seniority, and an empty list with an explanation is returned when no level structure is known. It also discloses a free-tier data limit (full detail for Amazon/Google/Microsoft/Meta/Apple, names only elsewhere), which materially affects result interpretation.

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?

Front-loaded with purpose, then sequencing, then limits, then slug discipline — dense and mostly waste-free. Minor slack: the trailing 'REQUIRED arguments: companySlug, jobFamilySlug' restates the schema, and the locationSlug/countrySlug mention is noise for a 2-parameter tool.

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 two-parameter read with annotations and no output schema, the description covers purpose, ordering, return shape (names plus alternates), empty-result behavior, and data-coverage limits. Nothing needed to call or interpret it is missing.

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 100%, so the baseline is 3; the description adds real value by mandating canonical slugs and pointing at the resolver tools rather than allowing name input. It loses a point for referencing locationSlug and countrySlug, which are not parameters of this tool.

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 verb and resource (internal level names per job family, ordered by seniority) and gives concrete examples of the naming convention it returns. It explicitly distinguishes itself from the sibling get-salaries-by-company-level, so an agent can tell the two apart without opening either 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?

Explicit sequencing guidance: 'Use this FIRST when a question names a specific level at a specific company... then call get-salaries-by-company-level,' including a worked example query. It also names the prerequisite resolution tools (search-job-families, search-locations, search-companies) and forbids guessing slugs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered by structured data. The description adds real behavior beyond that: the omit-topic fallback returns the union of all topics, and negotiation_coaching carries a usage restriction. It does not describe the shape of the returned reference material (format, size), which is the remaining gap.

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?

Three sentences, front-loaded with the purpose, and the topic enumeration earns its length because it drives selection. There is mild repetition between the topic list and the follow-up 'Covers ...' sentence, which restates several entries rather than adding to them.

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 zero-required-parameter, single-enum reference tool with no output schema, the description covers what to fetch, what each value means, and the default behavior. The only missing piece is the form of the returned reference content, which an agent might want before deciding whether to fetch all topics at once.

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 100%, so the baseline is 3, but the description earns above that by annotating the enum values themselves — 'the standard level ladder', 'vesting patterns', 'how to resolve locations / job families / enums' — which the bare enum list does not convey. Some entries (enums, company_groups) are glossed only loosely.

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 names a specific verb and resource ('Get reference knowledge about the Levels.fyi data model') and immediately enumerates the eight topics, which signals a documentation/reference tool rather than an entity fetch. An agent can distinguish it from siblings like get-company or get-vesting-schedules without opening the 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?

It gives an explicit conditional for a delicate topic ('negotiation_coaching ... use it only when the user asks for help negotiating') and states the default ('Omit "topic" to get every data-model topic'). It stops short of routing against near neighbors such as get-metric-explanation or get-vesting-schedules, so no cross-tool preference is stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the shape of the response (full text, locations, pay range, Levels.fyi estimated comp with matchesThisPosting flag, applyUrl) — important since no output schema exists. It does not address failure modes for invalid or expired jobIds, keeping it below 5.

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?

Front-loaded with the core action, and the field enumeration earns its space because there is no output schema to convey the return shape. The closing 'REQUIRED arguments' sentence is mildly redundant with the schema's required array, a small amount of waste in an otherwise tight description.

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 correctly compensates by listing returned fields, including the non-obvious USD currency and the matchesThisPosting marker semantics. It is nearly complete for a one-parameter read tool; only error/expiry behavior is unaddressed.

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 100% and the single parameter's schema description ('A jobId from search-jobs') already carries the meaning. The description's 'REQUIRED arguments: jobId' largely restates the schema's required list rather than adding syntax, format, or provenance detail, so the baseline 3 is appropriate.

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 verb and resource ('Get one job posting by its jobId') and explicitly anchors it to the search-jobs sibling, so an agent can tell it apart from search-jobs without opening a schema. It goes further by enumerating the payload the tool returns, making the scope of the operation unambiguous.

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 phrase 'by its jobId from search-jobs' plus 'REQUIRED arguments: jobId' makes the intended workflow clear: search first, then fetch by id. It stops short of stating exclusions (e.g., what to do if the posting has expired or the id is stale), so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnly=true, destructive=false, and closed-world, so the safety profile is covered; the description adds what the call actually yields (focus areas with titles plus untagged titles). It does not say what happens with an unknown or malformed slug, which is a minor behavioral gap.

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?

Three short sentences, all front-loaded with the core action before the discovery hint and the ordering guidance. No filler or repetition.

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 does the work of explaining the return payload (focus areas, their titles, untagged titles) and the prerequisite lookup path. Only error/empty-result behavior for an invalid slug is left unstated.

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 100% with a single string parameter and examples already listed in the schema. The description's "REQUIRED arguments: jobFamilySlug" restates the schema rather than adding meaning beyond "by its slug".

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?

"Look up a job family by its slug and get its focus areas (specializations) with their titles, plus untagged titles" gives a specific verb, resource, and scope of returned content. It is clearly separable from the sibling search-job-families tool, which the description names explicitly.

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?

It states a concrete downstream use case ("to find focusTagSlugs for the benchmark tools") and routes the agent to search-job-families when only a name is known. Both the when-to-use and the alternative are spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is all-or-nothing ('Errors if any slug is invalid'), meaning a single bad slug fails the whole batch, and it warns about array coercion for single values.

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?

Front-loaded with purpose and return fields, then routing, then the failure mode and array rule — a sensible order with no filler. The 'REQUIRED arguments: locationSlugs' line largely repeats the schema's required array, so it is mildly redundant.

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 read tool with annotations covering safety and no output schema, the description covers return fields, error semantics, and input coercion. Minor gaps remain, such as any limit on how many slugs can be passed in one call.

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 100% with an example, so the parameter is documented structurally. The description still adds meaning: it clarifies the parameter accepts 'one or more' slugs and that a single value must still be wrapped in an array — a real failure mode not stated in 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?

States a specific verb (look up) and resource (location slugs by identifier) and enumerates exactly what is returned: name, type (country / metro-DMA / state), parent country, currency, coordinates. It also implicitly separates itself from the name-based search path by pointing to search-locations.

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?

Explicitly says 'Use search-locations first if you only have a name,' giving a clear routing condition to the most confusable sibling. However, it does not distinguish itself from get-location-stats, another location sibling an agent could plausibly pick for detail-style queries.

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

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

Adds substantial context beyond the readOnly/destructive annotations: a 2-year lookback window that differs from the sibling's 12 months, a result cap of 10, USD currency, and the absence of company/level filters. It is docked slightly because the "Free limit:" sentence is garbled/truncated and the slug list references companySlug, which is not a parameter of this tool and could mislead an agent about available filters.

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?

Front-loads the core purpose well, but the middle section is dense and repeats itself (ranking/window explained twice), and the "Free limit:" fragment is an incomplete sentence that reads as a copy-paste error. The companySlug mention is also dead weight for a 2-parameter tool.

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 simple two-parameter read with readOnly annotations and no output schema, the description covers ranking metric, time window, currency, result cap and slug prerequisites — enough to call it correctly. Absent output schema, it partially compensates by saying what comes back (up to 10 locations with their median).

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 100%, so the baseline is 3; the description goes further by insisting both parameters are required, that they be canonical slugs resolved via search tools rather than guessed, and that countrySlug must be a country (cities/metros/states rejected, which the schema also states). The stray companySlug reference is the only noise.

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?

Specific verb and resource: top-paying locations for a job family within one country, ranked by p50 median yearly total comp in USD over the last 2 years, capped at 10 results. It also explicitly distinguishes itself from get-salary-percentiles, so an agent can tell the two apart without opening either 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?

States the intended use ("compare where a role pays most inside a country") and names the alternative with the condition that selects it ("quote get-salary-percentiles for one location's pay"). It also gives a prerequisite workflow: resolve names with search-job-families / search-locations / search-companies and never guess a slug.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds non-obvious behavior beyond the annotations: an unrecognized metric returns the list of known metrics instead of erroring. It doesn't describe the shape of the explanation payload, but nothing contradicts the annotations.

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?

Front-loaded with purpose, then the metric list, then the unknown-metric fallback, then the required arg. Efficient overall; the trailing 'REQUIRED arguments: metric' heading is mildly redundant with the schema's required array.

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 one-parameter, read-only explainer with no output schema, the description says what the answer contains (meaning, formula, caveats) and how invalid input resolves, which is enough for an agent to call it correctly. Only a hint at the actual return structure is missing, which is a minor 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 100% and the single parameter's schema already documents examples and case/separator-insensitivity. The description reinforces this with a longer example set but contributes no additional syntax or matching rules beyond the schema, so the baseline of 3 applies.

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 verb+resource ('Explain a Levels.fyi compensation metric or concept') plus the exact output content (meaning, formula, caveats), and enumerates concrete metric examples like 'TC', 'vesting', 'sign_on'. That scope cleanly separates it from lookup siblings such as get-vesting-schedules or get-domain-knowledge.

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?

Makes the usage case explicit — call this to resolve what a metric means — and adds a concrete fallback path: 'Pass an unknown metric to get the list of known ones.' It doesn't explicitly name alternatives like get-domain-knowledge for broader concepts, so there is no stated exclusion, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely non-inferable behavior: the exact response token ('pong'), the echo of the optional message, and the fact that the response includes a table of per-tool outputs and rate limits — the latter is the key operational detail an agent could not guess.

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?

Three compact sentences: purpose first, response contents second, invocation guidance last. No filler, and the most decision-relevant instruction (when to call) is not buried. Minor deduction because the response-contents clause and the rate-limits clause are compressed into one run-on sentence.

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?

There is no output schema, so the description carries the burden of describing returns — and it does, naming the ping token, the echoed message, and the tool/rate-limit listing. For a single-optional-param read-only diagnostic, that covers what an agent needs to call and interpret it.

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?

Only one optional parameter, and schema description coverage is 100%, so baseline is 3. The description's 'echoes an optional message' merely restates what the schema already says without adding format, limits, or edge-case behavior.

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 states a concrete function: a connectivity check for the Levels.fyi MCP server that returns "pong", echoes a message, and enumerates per-tool return shapes and rate limits. That is specific enough for an agent to act on, though it conspicuously diverges from the tool name 'get-permissions', which suggests permission retrieval rather than a health probe — the description has to correct the name rather than reinforce it.

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 ('call it when a result looks smaller than expected, instead of retrying'), which is a clear when-to-use directive with a named alternative behavior (retrying). It stops short of stating when NOT to call it or naming which sibling to prefer, but for a diagnostic tool the routing instruction is unusually actionable.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real value beyond them: the enumerated return payload, resume parse-state values (none/pending/parsed/failed), and the privacy guarantee about contact details and resume files. It omits edge behavior such as what happens when no profile exists or the user is unauthenticated, keeping it below a 5.

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?

Front-loaded with the core action in the first clause, then the return payload, then usage. The long field enumeration is justified because there is no output schema, though the resume-status parenthetical is slightly wordy relative to its importance.

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 compensates well by enumerating returned fields and resume status states. It lacks failure/empty-state behavior (no profile, not signed in, auth requirement), which an agent would need for a personal-data endpoint.

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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly does not invent parameter semantics for a no-arg call.

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 verb and scoped resource: 'Get the signed-in user's own Levels.fyi career profile', then enumerates the returned fields (title, company, level, job family, focus area, location, YoE, skills, certifications, work history). No sibling tool overlaps with 'my own profile', and the 'Never returns contact details or the resume file' clause draws a clean boundary.

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?

Explicitly tells the agent when to use it: 'to personalize answers about the user's own pay, level or career.' It also states a scope exclusion (no contact details, no resume file). It does not name an alternative for adjacent needs (e.g. get-permissions, upload-resume for resume actions), so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior: the 12-month lookback window, the requirement of a known level structure (a failure mode), and the free-tier limit that omits percentiles and counts. It does not say what an empty result looks like or how many levels are typically returned, which is the only meaningful gap.

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 purpose is front-loaded in the first sentence, followed by prerequisites, then limits, then slug resolution — a sensible priority order with no filler. The trailing 'REQUIRED arguments' sentence largely duplicates the schema's required array, which is the one redundant element.

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 three-slug read tool with no output schema, the description covers the data window, currency, metric definition (p50 of yearly total comp), the axis of aggregation (internal level), the free-tier truncation, and the full prerequisite/slug-resolution chain. An agent has everything needed to call it correctly and interpret the result.

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 100% and each parameter's description already instructs resolving with search-companies, search-locations and its parent-metro rule. The description repeats that guidance and adds 'never guess a slug' plus a restatement of the required list, so it adds emphasis but little new semantic content beyond the schema. Baseline 3 applies.

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 verb and resource: median (p50) yearly total compensation per internal company level, for one company, one job family, one location, over a 12-month window. It scopes itself against siblings by naming 'get-company-levels' as a prerequisite and ruling out 'percentiles or counts' (the domain of get-salary-percentiles). An agent can distinguish it from every other salary tool without opening a 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?

Explicit preconditions and ordering: call get-company-levels first, the company must have a known level structure, and slugs must be resolved via search-job-families / search-locations / search-companies rather than guessed. It also names the sibling it is not (percentiles/counts), so the when-to-use versus alternatives is fully covered.

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

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

Annotations already cover read-only/non-destructive safety, so the description correctly spends its words elsewhere: the 12-month submission window, the free-tier ceiling listing what is NOT returned (other percentiles, sample size, level split, company/focus-area/funding filters), and the never-guess-a-slug rule. It stops short of describing the response shape or behavior when data is sparse, which is the remaining gap given there is no output schema.

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?

Front-loaded with the definition, then alternatives, then limits, then slug rules — a sensible priority order with no filler. The "Free limit:" sentence restates the opening line almost verbatim before adding the exclusions, a minor redundancy.

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 two-parameter read with no output schema, the description covers what is measured, the time window, currency, exclusions and slug prerequisites — enough to call it confidently. Missing edge-case behavior (empty results, sample-size thresholds) is the only shortfall.

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 100%, so the baseline is 3; the description earns above that by adding the canonical-slug contract and naming the specific resolver tools (search-job-families, search-locations, search-companies) plus the 'never guess a slug' rule, which is operational guidance the schema does not state.

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 precise verb and resource with full scope: median p50 yearly total compensation in USD, one job family, one location, all levels, last 12 months. It explicitly distinguishes itself from get-location-stats and get-salaries-by-company-level, so an agent can pick it without opening sibling schemas.

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?

"This is the figure to quote for one location's pay" gives an affirmative use case, and the two sibling comparisons give explicit alternatives with the condition (longer window, per-company-by-level) that selects them. Prerequisite workflow (resolve slugs with the search tools first) is also stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: a free-tier limit that returns only base salary and total compensation, and the USD normalization rule vs. originalCurrency. It could still clarify what happens when a UUID is unknown or the row is out of plan scope.

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 return fields are front-loaded, followed by currency semantics and the free-tier caveat, so the most decision-relevant content comes first. The closing 'REQUIRED arguments: uuid' sentence is pure redundancy against the schema and slightly dilutes an otherwise tight definition.

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?

There is no output schema, so the description must carry the return shape — and it does, field by field, plus the currency semantics an agent would otherwise misread. Combined with the free-tier limitation and the uuid provenance, nothing material is missing 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?

With one parameter at 100% schema coverage the baseline is 3, and the description earns above that by telling the agent where the uuid comes from (a search-raw-data-points row) rather than leaving the format unexplained. 'REQUIRED arguments: uuid' merely restates the schema's required array.

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 verb and resource ('Get a single salary submission by its UUID') and enumerates exactly what comes back: company, title, level, location, YoE, offer date, base and total comp. That field list clearly separates it from the aggregate siblings like get-salary-percentiles and get-salaries-by-company-level.

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?

'Use the uuid from a search-raw-data-points row' explicitly routes the agent to the sibling that produces the required identifier, which is the main usage decision for a by-id lookup. It doesn't state exclusions (e.g. when to prefer search-raw-data-points instead of this call), so it falls short of a full when/when-not treatment.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful context about the shape of the decoded output (cliff detection, backloaded patterns like 5/15/40/40, plain-English description), but says nothing about failure modes, unknown slugs, or rate/volume limits.

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?

Dense and front-loaded with the output contract first, then the input requirement and the array-shape caveat. It runs long in a single block and mixes return-value detail with invocation rules, but no sentence is pure filler.

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 one required parameter, no output schema, and no nested objects, the description compensates well by describing the returned vesting fields in detail so the agent needn't guess. It lacks coverage of edge cases (missing/unknown slugs, multiple companies returned in what container), which keeps it from full marks.

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 100% and the single parameter is typed as an array with an example, so the description's array-must-be-array reminder mostly restates the schema. The one genuine addition is that values are company slugs resolvable via search-companies, which gives the agent a source for valid values.

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?

Names a specific verb+resource ('Get equity vesting schedules') and enumerates exactly what is returned (per-year percent, frequency, cliff, back/front/linear loading, RSU vs options). It does not distinguish itself from the sibling search-companies-by-vesting, which sounds like an adjacent capability, so sibling differentiation is only 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?

Gives a concrete prerequisite/workflow: 'Pass company slugs (use search-companies to resolve names first)', which is real routing guidance to another tool. It stops short of saying when to prefer this over search-companies-by-vesting or what to do when a slug yields no data.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. Beyond that, the description discloses that results come as a single ranked list with each item tagged by type and slug/id, and mandates surfacing entity-type mismatches to the user instead of silently substituting — a non-obvious behavioral constraint not present in any structured field. It stops short of describing empty-result or pagination behavior, so not a full 5.

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?

Three sentences, front-loaded with the scope and entity list, followed by routing guidance and then the mismatch rule. The first sentence is dense with parenthetical enumerations, but every clause carries decision-relevant information and nothing is filler.

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 available, the description supplies exactly the missing piece — the shape of the return value (single ranked list, type- and slug-tagged) — plus routing guidance across a 27-tool sibling set. An agent has everything needed to call it and to interpret or escalate its results correctly.

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 100%, so the schema already documents limit, searchText, and excludeFamilyLikeTitles semantics. The description only restates that searchText is required and enumerates the covered entity types; it adds nothing about the limit range or the excludeFamilyLikeTitles flag beyond the schema. Baseline 3 applies.

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 verb and resource ('Search across ALL entity types'), enumerates every entity type covered, and explicitly contrasts itself with the type-specific search siblings. An agent can distinguish it from search-companies or search-job-titles without reading 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 when-to-use ('you don't yet know which track an entity belongs to, or to disambiguate an ambiguous name') and a when-to-prefer-alternative rule naming five concrete sibling tools. It even prescribes a workflow for the cross-type mismatch case, which is a genuine routing decision left to the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds non-obvious behaviors the annotations cannot: alias/former-name matching and the exact return shape ({ name, slug }). Minor gaps remain (no mention of the limit ceiling behavior here), keeping it at 4.

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?

Front-loads the purpose and the slug-resolution rationale, then layers fallback guidance and return shape in a logical order. Slightly wasteful: the closing 'REQUIRED arguments: searchText' duplicates the schema's required field.

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?

No output schema exists, and the description compensates by stating the exact return type (array of { name, slug }) plus empty-result behavior. For a two-parameter lookup tool, everything needed to call it correctly is present.

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 100%, and the schema already describes searchText as accepting current or former names, so the description largely repeats structured data. It does reinforce that searchText is required, but adds no syntax or format detail 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?

States a specific verb and resource ('Search companies') plus the concrete output ('Levels.fyi slugs'), and distinguishes itself from search-all by naming the fallback sibling. An agent can tell immediately what this returns and why slugs matter.

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?

Explicitly instructs 'Use this FIRST' as the resolution step before benchmark tools, and states the fallback condition ('If this returns no matches, fall back to search-all'). Both when-to-use and the alternative path are spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value with the ranking rule ('most data-rich first') and the fact that decoded vesting schedules are returned, but says nothing about how filters combine (AND vs OR) or default result size.

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 dense sentences with the filter dimensions and the return behavior front-loaded; nothing wasted. Slight overlap with the schema enum is acceptable given the compactness.

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 does explain the return shape and ordering. However, for a six-parameter search tool it leaves open the key calling questions: filter conjunction semantics and behavior with no filters applied.

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 100%, so the baseline is 3. The description largely restates the enum values already in the schema, adding only a modest hint ('backloaded like Amazon') that clarifies an otherwise opaque enum member.

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 verb and resource ('Find companies') scoped to equity vesting characteristics, and enumerates the filter axes (type, shape, years, cliff). This separates it in spirit from the generic search-companies and get-vesting-schedules siblings, though it never names them explicitly.

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 is implied by the filter list: use it when you want companies filtered by vesting traits. There is no explicit statement of when to prefer search-companies or get-vesting-schedules instead, and no note on what happens if all six optional filters are omitted.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it returns matching tags with slugs and returns no matches when nothing hits, triggering the search-all fallback. It doesn't mention pagination or the limit default, but with annotations carrying the safety context this is solid.

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?

Front-loaded with purpose and the slug-resolution use case, then the fallback. Mild waste from restating the requirement twice ('searchText input (required)' and 'REQUIRED arguments: searchText'), which the schema already enforces, but no sentence obscures the key routing information.

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?

No output schema exists, and the description compensates by stating the return shape (matching focus tags with their slugs). The limit parameter's effect on result count is left to the schema, which documents it, so an agent has enough to call this correctly.

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 100%, so both parameters are already documented in the schema, including the 'focus tag / specialization name' phrasing and the 1–15 limit range. The description repeats that searchText is required and gives examples, which is redundant with the schema rather than additive, so the baseline 3 applies.

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 verb+resource (search focus tags), defines what a focus tag is with concrete examples, and states what the caller gets back (slugs). It is clearly distinguishable from the sibling search-* tools, which search companies, jobs, locations, and so on.

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?

Explicitly says when to use it ('resolve a specialization into the focusTagSlugs the benchmark tools accept') and what to do when it fails ('fall back to search-all, which searches every entity type and applies a fuzzy fallback'). Both the primary case and the fallback route are named.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by explaining the slug-resolution outcome and the no-match routing chain. It doesn't cover result ordering or whether matching is fuzzy/substring, which is a minor gap.

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?

Well front-loaded with purpose, then usage, then fallback. The trailing 'REQUIRED arguments: searchText' is redundant with the schema's required array and slightly restates earlier content, but overall the text earns its place.

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 two-parameter read-only search with no output schema, the description supplies what matters: what is returned (matching job families with slugs), why it matters (benchmark tools need the slug), and what to do on empty results. Nothing an agent needs to invoke it correctly is missing.

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 100%, so both parameters are already documented with examples and the 1–15 limit bound. The description only restates that searchText is required and gives role-name examples already present in the schema. Baseline 3 applies since the schema does the heavy lifting.

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 verb and resource (search job families/roles) and its output (Levels.fyi slugs), then distinguishes itself from search-role-terms and search-all by naming each. An agent can tell exactly what this returns versus its siblings.

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?

Explicitly says when to use it (resolving a role name into a jobFamilySlug that benchmark tools require) and gives a concrete fallback path: if no matches, go to search-role-terms, then search-all. It even warns that specific titles like 'UX designer' are not job families.

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

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

Beyond the readOnly/destructive annotations, it discloses the non-obvious result cap of 2 jobs per company, the fact that limit counts companies unless a single companySlug is supplied, that a page may hold fewer than limit, and how to page via nextOffset. Those are exactly the behaviors an agent cannot infer from the schema.

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?

Well front-loaded — purpose, return shape, then procedural rules — with no filler sentences. It is long for a description, and a few presentation directives (putting url on the title, card-dedup guidance) sit at the same weight as core search logic, but each rule is actionable.

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 13-parameter tool with no output schema, the description supplies the return shape itself ({ jobs, totalMatchingJobs, nextOffset } and per-job fields), query-construction rules, filter-resolution dependencies, pagination, and failure handling. Nothing needed to invoke it correctly is missing.

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 69%, and the description adds real meaning on top: array-typed arguments must be passed as arrays even for one value, locationSlug is single-valued and only for user-named locations, and query should be stripped of locations, salary and the user's own position. It leaves the enum-bearing params (standardLevels, employmentTypes, workArrangements) entirely to the schema, which is acceptable but not exhaustive.

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 — 'Search open jobs on Levels.fyi' — plus the differentiator that results carry pay ranges. It also names the sibling it is not ('Call get-job for a posting's full description'), so an agent can route between the two without opening either 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 explicit routing rules: resolve locations via search-locations, companies via search-companies, job families via search-job-families, and only one user-named location. It also covers the empty-result case (widen and retry once, then report honestly) and the profile-derived search flow, including the prohibition on calling get-profile without asking.

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

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

Annotations already cover the safe-read profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description doesn't need to restate safety. It adds real context beyond that: the shape of each result (id + parent job family), how callers should use that id downstream, and the no-match behavior. It doesn't mention result limits or ordering, which would make it a 5.

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?

Front-loaded with the core action, then result shape, then the tuning flag, then the fallback — a logical order with no wasted sentences. The trailing 'REQUIRED arguments: searchText' line is redundant with the schema and costs it a point, as does the slightly nested parenthetical about jobTitleIds.

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 carries the burden of explaining returns, and it does name the two fields that matter (id and parent job family). For a 3-parameter read tool with full schema coverage and clear annotations, this is close to complete; only the remaining result fields and ordering/limit behavior are unstated.

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 100%, so limit, searchText, and excludeFamilyLikeTitles are all documented in the schema. The description reinforces the exclusion flag's intent and the 'REQUIRED arguments: searchText' note, but that largely repeats the schema's required array rather than adding new semantics. Baseline 3 applies.

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?

Specific verb+resource ('Search specific job titles by name') that immediately distinguishes it from siblings like search-jobs and search-job-families. It also explains what the result is for: the id is the titleId consumed by the benchmark tools' jobTitleIds filter, so an agent knows exactly which tool family this feeds.

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 usage: use this to narrow a benchmark query to an exact title within a job family, plus a named fallback ('If this returns no matches, fall back to search-all, which... applies a fuzzy fallback'). It also states when to set excludeFamilyLikeTitles, so both the happy path and the failure path are covered.

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

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

Annotations already mark it read-only and non-destructive, and the description adds non-obvious behavior on top: omitting type searches countries/metros/states but never cities, city results carry a parent location whose slug is what the pay tools consume, and ambiguous names may match multiple places. These are exactly the traits an agent could not infer from the schema.

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?

Front-loaded with purpose and slug-resolution rationale before the fallback and ambiguity rules. Mostly earned length, though the trailing 'REQUIRED arguments: searchText' line duplicates the schema's required array and could be dropped.

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?

There is no output schema, and the description compensates by describing what results contain (location type) and the city-plus-parent shape that determines which slug to forward. Combined with the fallback path and the ambiguity guidance, an agent has everything needed to call it and interpret the response.

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 100%, so type, limit, and searchText are already documented in the schema with an enum and range. The description restates 'REQUIRED arguments: searchText' without adding syntax or format guidance, and never mentions limit. Baseline 3 is appropriate.

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 verb (search), an explicit resource set (countries, metro areas / DMAs, US states, plus city fallback), and the returned artifact (Levels.fyi slugs). It distinguishes itself from get-location (single lookup) and search-all by naming the latter as the fallback.

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?

Explicitly says when to use it (resolve a name into the slug the benchmark tools need), how to narrow with the optional type, and what to do on zero results (fall back to search-all, which applies a fuzzy fallback). It also gives disambiguation policy: pick the place the user means from context, ask if unsure.

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

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

Annotations only declare readOnly/non-destructive, which is the low bar; the description adds substantive behavior the agent could not infer: results are capped at 250 matches, only the newest rows are returned, the free tier returns just the 3 newest submissions with base salary and total compensation only, and every amount is normalized to USD with originalCurrency being merely the submission currency.

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?

Front-loaded with the core purpose, then proceeds through output shape, limitations, free-tier limits and slug prerequisites in a logical order. It is dense and somewhat long, but essentially every sentence carries operational information an agent needs.

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 supplies the return shape ({ total, rows }) and names the row fields, plus the 250-match cap and newest-only behavior. Combined with the free-tier caveat and required-argument note, nothing essential for a correct call is missing.

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 100% and the schema already states the slug format and names the resolver tools for each parameter, so the description's 'pass canonical slugs' and 'resolve names first' guidance largely echoes structured data. It adds marginal value via the 'REQUIRED arguments: jobFamilySlug' restatement, so baseline 3 is appropriate.

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 verb and resource: the newest individual salary submissions for a job family, with optional location/company narrowing. The phrase 'individual salary submissions' implicitly separates it from aggregate tools like get-salary-percentiles or get-salaries-by-company-level, but it never names or contrasts those siblings explicitly.

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?

Explicitly lists what is NOT supported (no text search, level, years-of-experience, sort or paging), states the prerequisite resolution workflow via search-job-families / search-locations / search-companies, warns 'never guess a slug', and flags the free-tier restriction. An agent knows both when to call this and when it cannot satisfy the request.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the shape of results: each hit is tagged with its type and slug. It does not discuss result volume, ranking, or empty-result behavior, so it stops short of a 5.

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?

Three sentences, front-loaded with the capability, then the selection heuristic, then the payoff. No filler and no repetition of schema details beyond the single required-flag note.

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 is simple (2 params, 100% schema coverage) and read-only, so the bar is modest. The description nonetheless compensates for the absent output schema by explaining that results carry type and slug tags, which is exactly the information an agent needs to act on the response.

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 100% and both parameters are documented in-schema, so baseline is 3. The description adds only the required-argument callout for searchText, which merely restates the schema's required list, and says nothing extra about how limit interacts with the result set.

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 verb (resolve) plus a named resource set (job families, job titles, focus tags) and the distinctive scope: searched TOGETHER in one call. That framing separates it immediately from the single-type siblings search-job-families, search-job-titles, and search-focus-areas.

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 selection condition — "use this when you're unsure whether a term ... is a job family, a specific title, or a specialization" — and contrasts it against the single-type searches via "TOGETHER in one call." It also states the downstream purpose ("feed the right one to the benchmark tools"), so the agent knows what to do with the output.

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

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

Annotations already cover read-only and closed-world safety, and the description adds real behavior: the result is capped at 10 companies, companies with too few submissions are silently excluded, values are USD medians, and a free-tier limit applies. The 'Free limit' sentence is garbled and never states what the paid tier unlocks, which keeps it from a 5.

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?

Front-loaded well with the core behavior in the first two sentences, but 'Median (p50) total compensation' is repeated, the required-arguments line duplicates the schema's required array, and the free-limit sentence is fragmented mid-description. Roughly a third of the text is redundant.

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 does the necessary work by stating the return shape (up to 10 companies plus their median), the currency, and the exclusion rule for thin data. Missing only minor details such as what identifies each company and whether ordering ties are broken.

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 100% and both parameters already carry examples plus the city/state rejection rule, so the schema does the heavy lifting. The description only restates that jobFamilySlug and countrySlug are required and repeats the slug-resolution advice, adding little semantic meaning beyond structured fields.

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 verb and resource ('Get the top-paying companies'), the scope (one job family, one country), the ranking key (median p50 yearly total compensation in USD) and the result cap (up to 10). This is clearly distinguishable from search-companies (slug lookup) and get-company-levels (per-level data) 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?

Explicitly says slugs must be resolved first via search-job-families, search-locations and search-companies, and warns 'never guess a slug' — a concrete prerequisite. It also names what is NOT supported (no sample size, level or years-of-experience filter), but stops short of routing the agent to the alternative tool for those needs.

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

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

Annotations only declare it is a non-idempotent, non-destructive write; the description adds the real behavioral burdens: mandatory user consent before sending, a hard prohibition on personal details, a conditional rule for contactEmail, and the return shape { received, id }.

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?

Front-loads purpose, then consent, then privacy, then return value — a good order with no filler. The final 'REQUIRED arguments' sentence is redundant with the schema's required array and is the one line that does not earn its place.

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 7-parameter write tool with full schema coverage and no output schema, everything an agent needs is present: consent gate, privacy constraint, conditional email, and the response shape.

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 100% and each parameter is already documented, so the baseline is 3. The description's restatement of the required arguments (kind, message) is redundant, and its contactEmail rule largely duplicates the schema's own description, adding only the privacy framing.

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 verb and object: report wrong/missing Levels.fyi data or a missing feature to the Levels.fyi team. It is clearly distinguishable from the many read-oriented siblings and from add-salary-submission, which is a data contribution rather than a feedback report.

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 precondition: only call after telling the user what will be sent and receiving agreement. It does not, however, route between alternatives (e.g., telling the agent to use add-salary-submission instead when the user wants to supply missing salary data).

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

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

Annotations already flag destructiveHint=true and idempotentHint=true; the description goes well beyond them by disclosing that the previous resume is replaced, that parsing happens in the background and can take a couple of minutes, that upload URLs expire in 10 minutes, and that a 201 response is the success signal. It also states a consent obligation ('tell the user Levels.fyi uses it to fill in their profile and match them with jobs') that no annotation carries.

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?

Front-loaded with the action, then constraints, then the two upload paths as bullets, then post-call behavior. The trailing 'REQUIRED arguments: fileType' restates the schema's required array and earns nothing, and the size/format limits are split between paragraph and bullet, but overall the density is justified by the operational detail.

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?

There is no output schema, so the description carries the return contract itself — and it does, explaining both the presigned S3 payload structure (url, fields, 'file' part), the 201 success signal, and the web fallback. Size limits, page limit, expiry, async parsing, and the verification step are all covered; nothing an agent needs in order to call this correctly is missing.

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 100% and the enum is self-documenting, but the description still adds real meaning: fileType must be set from the file's actual extension, and a mismatch means the file cannot be read. It also supplies the operational constraints the enum cannot express (PDF at most 5 pages, DOCX or PDF, at most 4.5 MB).

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 verb pair and resource: 'Add or replace the signed-in user's resume on Levels.fyi.' No sibling tool touches resumes, and the account scoping ('signed-in user's') is stated explicitly, so there is no ambiguity about which tool handles this.

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 ('Call this only when the user asks to upload their resume'), an explicit prohibition ('Never upload a resume for another person'), and a decision rule between the two upload paths (presigned S3 only if the agent can read the file and make HTTP requests; otherwise hand off webUploadUrl). It also names the follow-up tool: 'Call get-profile afterwards to check it.'

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