Level Jobs

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

With no annotations, the description carries the full burden and uses it well: it reveals that recently expired listings are included and that no direct ATS link is ever returned. It also instructs the agent to use the returned canonical url for applying, which is behavior an agent could not infer from the schema alone.

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 with no filler; the core purpose comes first and the ATS caveat earns its place. A model and clear example are woven in without bloating the 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?

For a one-parameter lookup with no output schema, the description covers input format, the expired-listing edge case, and expected link semantics. Nothing an agent needs in order 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?

The schema already documents id_or_slug at 100% coverage, so the baseline is 3. The description adds a concrete slug example and clarifies that both UUID and slug forms are valid, which helps an agent construct the parameter value correctly.

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?

Describes a specific operation — retrieving the full detail of a job listing — and identifies the exact identifiers accepted (UUID or slug). The mention of including expired listings and canonical URL helps distinguish it from search-oriented siblings such as search_jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is the tool for fetching a single known listing by UUID or slug rather than for discovery. It does not explicitly name search_jobs or state when not to use it, but the intended context is unambiguous.

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?

No annotations exist, so the description carries the full burden. It discloses a pure read operation ('Returns the definition') with no side effects, parameters, or mutation. For a trivial lookup tool there is little hidden behavior to disclose; the only minor gap is the lack of detail about the return structure, but nothing about the tool's behavior is misleading or opaque.

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 sentences with zero wasted words. The core fact — what the tool returns — is front-loaded in sentence one, and the contextual qualifier about the rating scale adds meaningful differentiation without bloat.

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-parameter, no-output-schema reference tool, the description is nearly sufficient: an agent knows exactly what it gets and why that matters. A small gap is that it doesn't hint at what each level definition contains (e.g., descriptions, examples, criteria), which would help an agent anticipate the return value, but this is minor given the tool's simplicity.

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?

Baseline 4 applies because the tool has zero parameters, so there is nothing for the description to clarify. Schema coverage is trivially 100% since the properties object is empty. The description needs no parameter explanations.

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 ('Returns'), a specific resource (definitions of Level's four AI-impact levels), and names the exact items (AI Level 1 to AI Level 4). The added scope statement — 'the scale every job listing is rated against' — clearly separates it from siblings like get_job and search_jobs, which operate on individual listings rather than the rating scale itself.

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?

No explicit when-to-use or when-not-to-use guidance, and no sibling alternatives are named. However, the clause 'the scale every job listing on jobsbylevel.com is rated against' implies the tool should be consulted when an agent needs to interpret AI levels attached to job listings. Usage is implied rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining the ranking basis, the score range, the exclusion criteria, and that the exact rule appears in a returned `method` field. It does not describe the full return shape or explicitly state it is read-only, but for a ranking tool the disclosed behavior is substantive.

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, each earning its place: the first states the ranking and metric, the second clarifies provenance and points to the `method` field, the third states exclusions. No filler or repetition; the most decision-relevant information is front-loaded.

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-optional-parameter ranking tool with no output schema, the description gives enough context: what is ranked, by what metric, with what exclusions, and where to find the exact rule. The only gap is that without an output schema, the exact return fields per company (e.g., company name, jobs count) are not spelled out.

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 schema already documents `limit` and `min_jobs`. The description adds some contextual meaning by tying 'too few live listings' to `min_jobs` and explaining the AI score scale, but it does not materially expand parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Ranks companies currently hiring on Level by how AI-native their open roles are.' It details the exact metric (average AI score, 0-100) and clarifies this is a Level-specific aggregation, not a third-party ranking. This clearly distinguishes it from siblings like search_jobs, which targets individual job listings rather than company-level rankings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description conveys clear usage context: use this tool when you want companies ranked by AI-nativeness of their live listings. It also states exclusions (companies with too few listings, job-board republishers). However, it does not explicitly mention when not to use it or name alternative sibling tools, so the routing guidance is clear but not fully explicit.

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?

With no annotations, the description carries the burden. It adds useful provenance ('Computed directly from the database, not an estimate') and scope ('currently published'), but it does not disclose return shape, default behavior, or any edge cases. This is helpful but incomplete for a tool with zero annotation coverage.

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?

A single dense sentence front-loads the resource and enumerates the exact statistics, followed by a short provenance qualifier. No filler or 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 one-optional-parameter read-only stats tool, the description covers the data scope and the dimensions returned. The lack of an output schema and annotations means exact response format is unspecified, but the tool is simple enough that the description is largely sufficient.

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%: top_n is fully documented with min/max and default. The description's mention of 'most frequent tools and categories' aligns with top_n but adds no new parameter 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?

Description opens with 'Aggregated statistics over currently published Level listings,' a specific resource and operation. It enumerates the exact dimensions (AI level distribution, remote share, top tools/categories), making the tool's purpose unmistakable. It doesn't explicitly contrast with siblings like search_jobs or get_job, so it stops short of full differentiation.

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?

No explicit when-to-use or alternative routing is given. The aggregate scope implies it is for market-level overview rather than individual job lookup, but the description never names search_jobs/get_job as alternatives. This is implied usage, not stated 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?

With no annotations provided, the description alone must disclose behavior, and it does: it caps results at 20, explains ranking by AI score and recency, and explicitly states that results link to the canonical jobsbylevel.com page and never to the employer's ATS. It also briefly defines the AI Level scale, which is not in the schema. It stops short of describing response structure or error/pagination behavior, but the key behavioral surprises are covered.

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 a compact paragraph that front-loads the purpose before moving to filters and result behavior; every sentence contributes either purpose, filtering semantics, or return constraints. No filler or repetition of the schema's parameter descriptions.

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 seven optional parameters, no annotations, and no output schema, the description covers the source, filtering dimensions, result cap, ranking order, and link behavior, which is enough to select and invoke it. It does not spell out the result object shape, but in the absence of an output schema, the description still gives the essential runtime constraints an agent needs.

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 value on top by explaining the AI Level scale ('AI Level 1 = AI is not the work, to AI Level 4 = AI is the job') and grouping the seven parameters into filter categories. It also clarifies ranking/result-limit semantics that give parameters like ai_level_min/max meaning beyond their type constraints.

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') and resource ('job listings published on Level'), and distinguishes the activity from siblings like get_job and market_stats by framing itself as the broad filtered search tool. It also adds domain context (AI Level ratings) so an agent understands exactly what kind of listings are searched.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through 'Search job listings' and enumerates filters, but it never explicitly tells an agent when to prefer search_jobs over a sibling like get_job or how to decide among them. It provides no exclusion or 'when not to use' guidance, so the agent must infer the division of labor from names.

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