CloudJobs

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

Annotations already cover read-only, idempotent, non-destructive and open-world behavior, so the description adds value by enumerating exactly what the response contains and by imposing a citation/attribution requirement on the returned URL. It does not say what happens when the company is unknown or when both resolution keys are omitted.

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?

One front-loaded sentence opening with the verb and source, then a compact enumeration of return fields. The field list is dense but every item describes a distinct payload 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?

There is no output schema, so enumerating the returned fields is genuinely useful and done well. The remaining gap is the zero-required-parameters ambiguity: the description never says what is returned or whether it errors if neither name nor slug is supplied.

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 are documented, so the schema does the heavy lifting. The description only adds a slug format example ('amazon-web-services') and no guidance on precedence between name and 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?

States a specific verb+resource ('Fetch a company profile from CloudJobs') and the two lookup keys (slug or name). It is clearly distinguishable from sibling search_companies, though it never names that sibling explicitly to complete the routing.

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?

Implies the workflow of getting a slug from search_companies (shown in the schema) and tells the agent to cite the profile URL, but gives no explicit when-to-use/when-not guidance relative to overlapping siblings like get_salary_data or get_job_market_overview.

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 safety (readOnly, idempotent, non-destructive, open world), so the description earns credit by adding the section-fallback lookup behavior, the fact that only metadata plus a short excerpt come back, and the citation obligation with the returned URL. Those are real behavioral traits not expressed in the annotations or 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?

Three tight sentences, front-loaded with the resource and identifier, then lookup behavior, then the return-shape and citation constraint. No sentence is redundant with another.

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 return-value burden and does it — metadata plus a short excerpt, full text only on-site. Missing only edge-case behavior such as what happens when no section matches, which matters for an open-world lookup tool.

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 section enum already documents the default and fallback, so the description largely restates structured data. It adds the useful framing that a wrong section guess is non-fatal, but no slug format or matching guidance beyond the schema example.

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 — 'Fetch a CloudJobs insight post by slug' — which clearly separates it from search_insights (search) and the other get_* tools (company, job, salary). It stops short of naming the sibling it complements, so an agent must infer that search_insights is the discovery counterpart.

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?

Implies usage: you need a known slug, and the section fallback behavior tells the agent it need not pick a section precisely. There is no explicit when-not or a named alternative such as search_insights for the case where the caller has only a topic, not 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 readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered and the description is free to add value elsewhere. It does so by enumerating what the response contains (full description, salary range, technologies, certifications, canonical and external URLs), which tells the agent what it gets back before calling. That is meaningful disclosure for a tool with 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?

Three short sentences, front-loaded with the identification method before the return contents and the citation instruction. The slug form is restated from the schema, a minor redundancy, but nothing else is padding.

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?

A single-parameter read tool with rich annotations and no output schema, so the description carries the return-value burden itself — and it does, listing the fields returned and both URLs. An agent has everything needed to call it correctly and to present 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 the single 'id' parameter is already documented with a concrete example and the 'title--id' slug form. The description merely repeats that same slug form, adding no new constraint, format rule, or edge-case handling. With one fully documented parameter this is the expected baseline rather than a strength.

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 ('Fetch the full details of a single CloudJobs listing by id') and the word 'single' implicitly separates it from a bulk/list tool like search_jobs. It stops short of naming the sibling alternative explicitly, so an agent infers the split rather than being told.

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 only implied: the agent deduces this is the detail-lookup step after obtaining an id from a search. There is no explicit 'use this when you have an id, use search_jobs when you don't' statement and no when-not guidance. The one actionable directive ('Cite the cloudjobs.io URL when presenting the job') is about output presentation, not tool selection.

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real value: a ~30 minute cache window that tells the agent about data freshness. The instruction to cite links in the result also sets an expectation about output usage. It stops short of stating payload size or pagination behavior, but that is minor for a zero-parameter snapshot.

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 content is front-loaded: the snapshot contents come first, then the usage trigger, then the caching and citation caveats. Every clause carries information (what is returned, when to call it, freshness, citation rule) and there is no 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, the description compensates by enumerating the return contents in detail, plus a freshness caveat and a citation expectation. For a simple, zero-parameter, read-only aggregate tool, an agent has everything needed to select and call it 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?

There are no input parameters, so there is nothing to disambiguate; the baseline for a zero-parameter tool applies. The description correctly signals that no inputs are needed, letting an agent call it directly without schema inspection.

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 resource and enumerates its scope: totals, company count, remote/hybrid/onsite split, 7-day postings, salary coverage, and top technologies, locations, and certifications. It clearly distinguishes this aggregate snapshot from per-entity siblings like get_job, search_jobs, and get_salary_data.

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 explicit when-to-use framing: "Use for 'state of the cloud job market' questions." That is clear context, but it does not name alternatives or exclusions — an agent must infer on its own that per-company or per-salary questions belong to get_company or get_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 declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond them: answers and explanations are stripped by default, the product rationale (drive users to the interactive quiz), and the instruction to cite quizUrl. It does not mention pagination defaults or behavior on unknown/part testIds.

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 and the required input, then return shape, then the answer-suppression default and its rationale, ending with a presentation instruction. Every sentence carries actionable information with no 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, the description valuably enumerates returned fields (question text, options, doc links, quizUrl) and explains the deliberate omission of answers. Remaining gaps are secondary: no default page size for limit/offset and no guidance on the section filter.

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 60%, and the description compensates in part by clarifying testId formats including part ids ('saac03-2', 'saac03-bonus') and the meaning/consequence of includeAnswers. limit, offset, and section are left entirely to the schema, and limit/offset have no schema descriptions at all.

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 ('Fetch practice exam questions for a CloudJobs study test') and anchors the required testId to its source (list_practice_tests, e.g. "saac03"). It is clearly distinguishable from siblings like list_practice_tests or get_site_guide.

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 to list_practice_tests for obtaining testId and explains the default answer-suppression so agents know when to set includeAnswers: true. No explicit when-not-to-use case or named alternative for other resource types, so it falls short of 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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely new behavior: roughly 30-minute caching (freshness caveat) and that salaries are annual USD normalized ranges. It does not disclose sample sizes, minimum data thresholds, or what happens when a filter yields too few postings.

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 dense sentences with no filler: capability, constraint, then output semantics and freshness caveat. The most important constraint (single filter) is front-loaded immediately after the purpose statement.

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 return-shape burden and does so by enumerating the statistics returned plus units and normalization. Missing only secondary details — sample size, how quartiles are computed, and behavior on sparse filters — which are minor for a statistics lookup.

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 0%, so the description must carry the burden, and it does: it supplies examples for technology ('AWS'), certification ('SAA-C03'), domain ('AWS', 'security'), location, and the remote type, plus the non-obvious constraint that exactly one of the five may be supplied. It leaves some ambiguity unresolved, notably that 'AWS' is offered as an example for both domain and technology, and doesn't say whether remote should be passed instead of or in addition to another filter.

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 ('Get salary statistics'), enumerates the exact statistics returned (min, quartiles, median, max), names the data source (CloudJobs postings), and distinguishes it from listing-oriented siblings by pointing to jobsUrl for live filtered listings.

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 a concrete usage rule — 'Provide exactly one filter' — and steers agents wanting individual postings toward the jobsUrl/live listings path rather than this aggregate tool. It stops short of naming the sibling tool (e.g. search_jobs) explicitly, so the alternative is implied rather than routed.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the tool is a static reference map and its URLs are canonical and should be preferred over others. It does not describe the return payload's structure in detail, but for a no-parameter lookup this is largely sufficient.

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 tight sentences, front-loaded with what the tool is, followed by the directive on how to use it. Every clause carries information; the parenthetical section list doubles as scope disclosure rather than 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 parameters, no output schema, and simple read-only annotations, the description carries the right amount of load: it explains what the returned map contains and how to apply it. Nothing an agent needs in order to call and use this tool 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 tool takes zero parameters, so there is nothing for the description to disambiguate. Per the baseline for 0-param tools, a 4 is appropriate; the description correctly implies no input is required by framing the tool as a fixed site map.

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 resource ('Map of the CloudJobs website') and states exactly what it returns: section contents plus canonical URLs. It enumerates the covered areas (job search, company profiles, salary insights, market reports, practice tests, methodology), which makes it immediately distinguishable from siblings like get_company or search_jobs that return actual records rather than a navigation map.

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 context for use: 'Use this to direct users to the right page' and 'Always prefer these URLs when sending users somewhere on CloudJobs.' That is a clear directive plus a default-behavior rule. It stops short of naming when NOT to use it (e.g., when the user wants data rather than a link), so it is not a full when/when-not/alternatives 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 readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds genuinely new behavioral detail: entries map to curated /jobs/<slug> pages and two slugs can be composed as /jobs/<slug1>/<slug2> (e.g. /jobs/aws/remote), which an agent could not derive from annotations or the empty schema. It does not say whether the category list is static or refreshed, which is the only notable 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 tight sentences, front-loaded with what the tool lists, followed by entry structure, then the composition rule, then citation guidance. No filler or redundant restatement of the title.

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 read tool with full annotation coverage and no output schema, the description supplies enough: what the entries are, how slugs compose, and when to cite them. The one missing piece is the shape of each entry (what fields accompany a slug/link), which matters slightly more here because there is no output schema to describe 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?

The tool takes zero parameters and the schema is empty, so there is no parameter meaning for the description to add. Baseline 4 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 ("List CloudJobs SEO landing pages for job categories") and enumerates the category dimensions covered (technologies, certifications, locations, experience levels, remote). This is clearly distinguishable from search_jobs and get_job, which return individual postings rather than category index pages.

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?

"Cite these URLs for category-level job questions" gives a clear usage condition and implicitly excludes job-level or salary-level questions. It does not explicitly name the alternative tools (e.g., search_jobs for individual roles), so an agent must infer the boundary rather than being routed.

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, idempotent, non-destructive, and open-world, so the safety profile is covered. The description goes beyond them usefully by enumerating the returned fields (test ids, question counts, duration, difficulty, canonical URL) with no output schema present, plus a citation obligation; only pagination/default-limit behavior is missing.

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, front-loaded with purpose then return shape then the citation convention. The vendor list is slightly redundant with the domain examples but earns its place by signaling coverage.

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 listing tool with no output schema, the description supplies the return-field inventory an agent needs and the URL citation rule. The remaining gap is paging/limit semantics, which is minor at this 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 coverage is 50% – only the domain filter is documented in the schema. The description partially compensates by enumerating the domain values (AWS, Azure, GCP, CompTIA), but says nothing about the limit parameter, its default, or pagination 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 opens with a specific verb and resource ('List the practice tests/quizzes available on CloudJobs study') and names the covered exam vendors, so an agent knows exactly what this returns. It does not explicitly contrast itself with the sibling get_practice_questions, leaving the tests-vs-questions distinction to be inferred from wording alone.

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 only implied: the instruction 'Cite the cloudjobs.io URLs when recommending a test' establishes a downstream convention but never states when to call this instead of get_practice_questions or search tools. No exclusions or prerequisites are given.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the return payload (salary medians, top technologies, workplace split, profile URLs) and an explicit instruction to cite canonical URLs when naming employers. It omits result limits and truncation behavior, 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?

Three sentences, front-loaded with the verb, resource and ranking, followed by return contents and one citation rule. Nothing is redundant or padded.

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 correctly fills that role by enumerating the returned fields. Against seven mostly undocumented optional parameters, though, an agent still lacks enough to call the filter and sort parameters confidently, so the definition is only partly complete for a tool of this breadth.

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 the query parameter is effectively explained ('With no query...'), and the default ranking is implied. With schema coverage at 29%, sort, limit, remote, location and technology are documented in neither the schema nor the description, so an agent gets no guidance on what the sort enum values do or how filters combine. That is a real compensation gap rather than an acceptable baseline.

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, 'Browse or search companies with open roles on CloudJobs', and states the ranking basis (open job count), which lets an agent separate this from search_jobs or get_company. It stops short of explicitly naming a sibling to defer to for a single employer, so it is clear but not fully differentiated.

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 empty-query case is documented well: 'With no query, returns the largest employers on the board' is a genuine usage rule. However, nothing says when to prefer this over get_company for a single profile, or over search_jobs when the goal is individual roles, leaving the alternatives implicit.

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, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape (titles, dates, canonical URLs) and the citation expectation, though it omits the result cap (limit max 25) and anything about result ordering beyond 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?

Two sentences, no filler, with the scope and content taxonomy front-loaded and the citation instruction last. Every clause 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 three-parameter, zero-required search tool with annotations and an inline summary of return fields, this is close to complete. A brief pointer to get_insight_article for full article bodies and a note on the 25-result ceiling would close the remaining 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 coverage is 67% with self-evident names; query and section carry their own descriptions and the section enum is enumerated in the schema. The description adds no meaning beyond that, 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 ('Search') and resource ('CloudJobs articles and market reports'), then enumerates the content families covered (evergreen guides, weekly/monthly analyses, basics explainers). By saying it returns titles, dates and canonical URLs, it implicitly separates itself from get_insight_article, which would return full post content.

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 rather than stated: an agent can infer it should search here first and then cite canonical URLs. There is no explicit 'use X instead when...' routing to get_insight_article for full text, nor any exclusion for when a direct lookup is better.

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, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds information annotations cannot convey: it returns job cards containing canonical cloudjobs.io URLs and the agent is instructed to always cite them. It stops short of describing pagination behavior or result caps, though pageSize maximum is visible in 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?

Three tight sentences with zero filler: purpose first, filter surface second, return-and-cite guidance third. The most important operational instruction (cite the canonical URLs) is front-loaded within the return-value 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?

With 12 optional parameters and no output schema, the description carries the burden of explaining what comes back, and it does so by describing job cards with canonical URLs. Combined with the annotations covering safety and the schema covering sort, paging, and enum values, an agent has enough to call this correctly. Minor gaps remain around result volume and pagination expectations.

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 67%, and the description closes much of that gap by naming the filter surfaces: free-text query, technology, certification, location, remote type, experience level, minimum salary, company, and certification domain, with AWS/Azure as concrete domain examples. It does not explain pagination or sort, but those parameters are already documented 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?

The description leads with a specific verb and resource ('Search live cloud/DevOps/IT job listings on CloudJobs') and names the domain, so an agent knows exactly what is being searched. It then enumerates the filter dimensions, which further distinguishes it from siblings like get_job and list_job_categories.

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 routes the agent: use search_jobs to find listings, and 'Use get_job for full descriptions' when detail is needed. It also imposes a citation obligation for the returned URLs. There is no explicit statement about when not to use it versus other discovery tools such as list_job_categories or search_companies, so it stops short of full when/when-not coverage.

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