Jobs Base

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

Annotations already declare readOnlyHint=true and openWorldHint=false, indicating this is a safe read operation with deterministic results. The description adds valuable context about what data is returned (specific fields like benefits and company info) and the typical workflow pattern, which goes beyond what annotations provide.

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 waste - the first sentence states purpose and scope, the second provides clear usage guidance. Every word serves a specific function, and the information is front-loaded with the most important details first.

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 operation with good annotations, the description provides appropriate context about what data is returned and how it fits into the workflow. While there's no output schema, the description enumerates the key return fields, making it reasonably complete for this tool's complexity.

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 the single parameter 'id' already documented as 'The job ID' in the schema. The description doesn't add any additional parameter semantics beyond what the schema provides, but the baseline is appropriate given complete schema coverage.

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 clearly states the specific action ('Get full details') and resource ('builder job by its ID'), listing the exact data returned (description, skills, experience requirements, benefits, company info). It explicitly distinguishes from sibling 'search_jobs' by specifying this is for retrieving complete listings after searching.

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

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

The description provides explicit guidance on when to use this tool ('after search_jobs to retrieve the complete listing'), creating a clear workflow relationship with the sibling tool. It effectively tells the agent to use search_jobs first, then this tool for detailed information.

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 indicate read-only and closed-world behavior, which the description aligns with by describing a data retrieval operation. The description adds value beyond annotations by specifying the types of filter values returned and the recommendation to call it first for discovery, enhancing context without contradicting 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?

The description is front-loaded with the core purpose in the first sentence, followed by actionable guidance. Every sentence earns its place by providing essential information without redundancy, resulting in a compact and well-structured text.

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 the tool's complexity (simple retrieval with no parameters), annotations covering safety, and no output schema, the description is largely complete. It explains what the tool does, when to use it, and what data it provides, though it could briefly mention the return format or data structure for full completeness.

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 0 parameters and 100% schema description coverage, the baseline is 4 as per the rules. The description compensates by explaining the semantic purpose of the tool (to retrieve filter values for search_jobs), which adds meaning beyond the empty input schema, making it clear why no parameters are needed.

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 clearly states the tool's purpose with specific verbs ('Get available filter values') and resources ('job types, workplace types, cities, countries, seniority levels, and companies'), and distinguishes it from sibling tools by explicitly mentioning 'search_jobs' as the related operation. It goes beyond a tautology by detailing what types of filter values are retrieved.

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

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

The description provides explicit guidance on when to use this tool ('Call this first to discover valid filter values before searching') and why ('especially for country codes and available cities'), and implicitly suggests alternatives by referencing 'search_jobs' as the subsequent step. It clearly defines the tool's role in the workflow.

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?

The description states 'All parameters are optional', but the input schema lists 5 required fields (salary_at_least, salary_at_most, experience_no_more_than, visa_sponsorship, limit). This directly contradicts the schema and annotations, which include readOnlyHint true. No other behavioral traits are disclosed beyond what the schema provides. The contradiction is a critical flaw.

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 front-loads purpose but is somewhat verbose, with redundant warnings about generic terms. The contradiction adds confusion. It could be more concise while retaining key guidance. Still, the structure is logical: purpose, context, usage rules, parameter advice.

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 18 parameters and no output schema, the description provides some context (board curation, avoid generic terms) but fails to clarify the contradiction about required fields, which severely impacts completeness. It does not explain return format or pagination beyond the cursor parameter.

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 description adds minimal value. It explains the 'q' parameter's constraints (avoid generic terms) and enumerates acceptable values for filters, but the contradiction about optionality undermines clarity. Baseline is 3 due to high schema coverage.

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 clearly states the tool searches and filters builder job listings on jobsbase.io, a curated board for specific roles. It distinguishes itself from siblings (get_job, list_filters) by focusing on search and filtering. The verb 'search' and resource 'builder job listings' with the board context make purpose 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 description explicitly advises against using generic terms like 'builder', 'AI', 'full-stack', or 'engineer', explaining they are redundant and hurt results. It directs to use 'q' only for specific technologies, companies, or domains. It notes all parameters are optional, guiding the agent on when to use each filter type. This is highly actionable.

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