rolefig

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, so the safety profile is covered. The description adds real behavioral value not present in the schema: it discloses the return content ('blocking errors, recommended fixes and a summary per posting') and a key negative ('never the page itself'), which matters because there is no output schema. It omits fetch/auth/privacy caveats for the `url` mode, 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?

Two sentences, no filler, and the core purpose plus validation target are front-loaded before the input-mode detail. Every clause carries 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?

With no output schema, the description correctly compensates by summarizing the return shape (errors, fixes, summary) and its exclusion of page content. Parameter semantics are fully covered, but behavior when both inputs are provided, or on fetch failure of `url`, is not addressed.

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 0%, so the description must carry parameter meaning, and it does: `html` accepts page HTML or JSON-LD, `url` accepts a public page address. That clarifies both parameters and the either/or usage implied by zero required fields, though it doesn't address whether both may be supplied simultaneously or how conflicts are resolved.

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 ('Check') and resource ('a job post's schema.org JobPosting markup') and names the external authority it validates against ('Google's job search rules'). This is clearly distinguishable from siblings like get_job, search_jobs, or check_pay_transparency.

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?

Explains the two input modes ('Pass the page HTML or JSON-LD as `html`, or a public page address as `url`'), which is genuine usage guidance for choosing how to call it. It does not, however, state when to prefer this over siblings such as check_pay_transparency or get_job, so it stops short of explicit 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add context beyond that. It does: it discloses data freshness ('table checked 2026-10-05'), the full shape of what is returned (applicable laws, what the post shows, what may be missing, official sources), and an explicit scope boundary ('not legal advice').

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, front-loaded with the core action before the input enumeration and the return/disclaimer clauses. The parenthetical enumerations are dense but each item adds real information, so nothing is wasted.

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 spends words on return contents and freshness, and it names a scope limit. It stops short of describing error or edge-case behavior (e.g., unmatched state, non-US posts) for a tool with three required inputs.

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 0%, so the description must carry the parameter burden, and it largely does: 'the job's state, optional city or county, total employer size and remote status' maps onto state, place, employees, and remote, while the surrounding text implies text is the job post body. It still omits format expectations (e.g., whether state is a two-letter code or full name) for the required state parameter.

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 ('Check a US job post against state and city pay-range posting laws') and scopes it to US jurisdiction, so the purpose is unambiguous. It does not, however, differentiate itself from the sibling check_job_posting, which an agent could plausibly confuse it with.

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 framing ('Check a US job post... for the job's state, optional city or county, total employer size and remote status'), which tells the agent what inputs to gather. There is no explicit when-to-use/when-not guidance and no mention of how it relates to the similar-sounding check_job_posting sibling.

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 annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: overtime is paid at 1.5x and the `hour` unit blends base and overtime pay.

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, front-loaded with the core operation and followed by critical calculation rules. Every sentence adds useful 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?

The annotations cover safety and the description covers core conversion behavior, but with 6 parameters at 0% schema description coverage and no output schema, more detail is needed about schedule parameters and the return value. It is adequate for understanding the tool's purpose, but not fully sufficient for confident invocation across all inputs.

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 0%, so the description must carry parameter meaning. It explains the unit values and mentions overtime hours, but it leaves daysPerWeek, hoursPerWeek, and weeksPerYear unexplained beyond the vague phrase 'stated schedule', and it does not clarify how those schedule parameters combine.

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 (Convert), resource (gross pay figure), and the full set of target units. It clearly distinguishes this pay-conversion utility from the job/company/resume siblings, so an agent can identify its purpose 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 clear context ('for a stated schedule') and an explicit scope exclusion ('Gross pay only: no taxes, benefits or deductions'), which tells the agent when this tool is not appropriate. It does not name alternative sibling tools, but no sibling performs pay conversion, so the practical guidance is strong.

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/closed-world. The description adds genuinely new context beyond them: the data is illustrative demo data and applications are closed, which materially affects how an agent should interpret and present results.

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 two-fragment description with no filler; every clause carries information about the tool's nature and output content.

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 read-only, no-output-schema tool this covers what is returned ('company profile and its roles') and the demo caveat, but leaves the one required parameter's provenance and format undefined.

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 single slug parameter has 0% schema description coverage, so the description must carry the burden, and it explains nothing about what a slug is, where to obtain one, or whether it accepts a company ID or name.

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 ('Read') and resource ('sample company profile and its roles'), and the 'Demo catalog' framing distinguishes it from production siblings like get_published_company.

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?

'Demo catalog: illustrative roles, applications closed' implies this is for demo/sample scenarios, but it never states explicitly when to choose this over get_published_company or demo_get_job, nor where a valid slug comes from (likely demo_list_companies).

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 closed-world, so the safety profile is covered. The description adds the meaningful caveat that this is illustrative data with applications closed, but says nothing about return shape or slug behavior.

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 short sentences, with the demo/illustrative scoping front-loaded ahead of the action. No filler, though it is terse to the point of omitting the parameter.

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 read-only lookup with full annotation coverage and no output schema, the description tells the agent what it returns (role plus company profile) and that the data is demo-only. Only the slug semantics are left 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 description coverage is 0% and there is one required parameter, slug, whose format or expected values (e.g., a role identifier from demo_search_jobs) are never explained. The description does not compensate for the schema gap 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 ('Read') and resource ('a sample role and its company profile'), and the 'Demo catalog' framing clearly separates it from the real-data sibling get_job. It does not name the sibling explicitly, so it stops short of a 5.

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 'Demo catalog: illustrative roles, applications closed' note implies when this is appropriate (sample/illustrative data, not live postings), but it never states when to prefer demo_get_job over get_job or demo_search_jobs. Usage is implied rather than 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context that the data is illustrative sample content with applications closed, but says nothing about result volume, ordering, or how role counts are computed.

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 tight sentence that front-loads the catalog nature and then the return content. 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?

For a read-only list tool with no output schema, the description conveys the rough return shape ('companies and their role counts') and dataset nature. However, leaving the sole parameter entirely unexplained is a meaningful gap in an otherwise simple definition.

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 is one parameter ('query') with 0% schema description coverage, and the description never mentions it, so an agent cannot tell whether it filters by company name, role text, or something else. The description fails to compensate for the coverage gap.

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 the sample companies and their role counts') and signals the demo/illustrative nature, which distinguishes it from demo_get_company. It does not explicitly name siblings, but the demo prefix plus the singular/plural distinction is inferable.

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 'Demo catalog' weakly implies a browsing/exploration context, but there is no statement of when to use this versus demo_get_company or list_published_companies, and no prerequisites or exclusions. The agent must infer usage from the tool name.

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, closed-world behavior, so the safety profile is covered. The description adds meaningful context beyond that: this is a demo catalog and applications are closed, so results are not actionable openings. It omits pagination behavior and result shape, keeping it 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 short sentences, front-loaded with the demo/non-actionable caveat and closing with the sibling routing. No filler, though the pass over filterable fields is a bare list rather than tight prose.

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 read-only search with no output schema and full annotation coverage, the description supplies what an agent needs: dataset nature, filters, and the correct alternative. It would be complete with a word on pagination defaults.

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 0%, so the description must carry semantics, and it maps four of six params to concepts (keywords=query, company, work arrangement=arrangement, minimum annual USD base salary=minSalary). It says nothing about limit/offset pagination or value formats such as the company slug pattern, leaving gaps the schema does not fill either.

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 gives a specific verb+resource ('Search the sample roles') and immediately frames the tool as a demo catalog of illustrative, closed roles. It names the sibling to use for real openings (search_jobs), so the agent can distinguish it 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 routing guidance: use this for sample/illustrative roles, and 'For real openings use search_jobs.' The when-not condition and the named alternative are both stated outright.

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 readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing that data is sent to 'rolefig' for remote formatting and that nothing is saved or submitted. It does not describe the shape of the returned resume text, which is the main remaining 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, scope constraint front-loaded, then exclusions, then the data-handling note. No filler, and each sentence changes how an agent would call the 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?

No output schema exists, so the description should say what comes back; 'format into resume text' only gestures at it. Combined with seven undocumented required parameters, an agent knows the boundaries but not the input expectations or the return value.

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?

All 7 parameters are required with 0% schema description coverage, so the description carries the full burden and largely fails: it never explains what name, headline, summary, experience, skills, or education should contain or how they are formatted. Only the 'contact' field gets indirect guidance via the omit-contact-details sentence.

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 ('Format ... into resume text') and immediately bounds the scope with 'ONLY candidate-supplied facts'. No sibling tool formats resumes, and the description makes that distinct role obvious 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?

Gives clear usage conditions: format only supplied facts, omit contact details unless the candidate wants them included. It does not name an alternative tool or a when-not-to-use case, but no sibling performs comparable work, so the remaining guidance is adequate.

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, so the 'Never submits an application' line is partly redundant reassurance. The added value is the data-semantics disclosure that compensation text is authoritative while absent numeric pay/units are unknown, which prevents the agent from hallucinating salary figures.

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 purpose, then parameter sourcing, then the two caveats. No filler; each clause carries 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?

There is no output schema, yet the description sketches the return contents and flags the compensation caveat, covering the highest-risk ambiguity. Only minor gaps remain (e.g., behavior when a slug is stale or unpublished).

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 0%, so the description must carry the parameter burden. It adds provenance ('slugs from search_jobs') but not format or case rules, which the schema handles via regex pattern. Adequate but not compensating fully for the coverage gap.

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 ('Read one current published opening in full') and enumerates what the result includes (company profile, application URL, rolefig page), which separates it from list/search siblings like search_jobs and list_company_openings. An agent can tell what this tool returns 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 tells the agent where the required identifiers come from ('Use the company and job slugs from search_jobs'), which is real routing guidance. It stops short of naming when to prefer this over check_job_posting or list_company_openings, so no explicit exclusions.

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, destructiveHint=false and closed-world, so the safety profile is covered. The description adds value beyond that: it discloses the result contents (application URLs, publication revision) and the filtering behavior (excludes drafts and closed jobs), plus reinforces the read-only boundary with 'Never submits an application'.

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 with no filler: the first states what is returned and scoped, the second states the two boundaries (what is excluded, what is never done). Fully 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?

With no output schema, the description usefully names the return fields (application URLs, publication revision). For a single-parameter read-only listing, the remaining gap is minor: no mention of result size, ordering, or pagination behavior.

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 parameter with 0% schema description coverage, but the JSON Schema pattern already encodes the slug format (lowercase, hyphen-separated). The description contributes the semantic that it must be an existing company slug rather than a name or query string, which is real but modest added meaning.

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 ('Read') and resource ('current published openings'), constrains scope to a 'known company slug', and distinguishes itself from siblings like list_companies and search_jobs by being company-scoped and publication-status-filtered. An agent can tell what this returns 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?

The phrase 'for a known company slug' is a genuine precondition hint — it tells the agent it must already have a resolved slug (e.g., from list_companies) rather than a free-text query, which is what separates it from search_jobs. It does not explicitly name an alternative tool or a when-not condition, so it stops 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, closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: the result set is public company information only with no applicant data, and results are cursor-paginated.

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, zero waste, with the core purpose front-loaded and the follow-up tool routing and data-scope caveat following in priority order.

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 usefully signals that the response carries a slug usable by other tools, and it bounds the data scope. The remaining gap is pagination semantics (how to obtain and reuse the cursor), which is only named, not explained.

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 0% for all three parameters, so the description must carry the load. 'search' implies what q does and 'cursor pagination' implies what after does, but nothing is said about limit, the cursor's opaque format, or default/maximum 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?

States a specific verb+resource ('Discover company-published profiles') plus the mechanism (search, cursor pagination), so the agent knows exactly what it returns. It stops short of explicitly differentiating from the sibling list_companies, leaving the published-vs-unpublished distinction to be inferred.

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 strong downstream guidance ('use the returned slug with get_published_company or list_company_openings'), which is implied usage for a discovery tool. However, it never says when to pick this over list_companies or when not to use it, so the selection guidance is incomplete.

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?

Goes well beyond the annotations: discloses the return payload (document text, best-effort warnings with a wage-table date, workspace Compensation/Offer terms texts, and an ATS offer object once candidate/start/expiry are set), the 'not legal advice' caveat, and that remote use transmits values to rolefig with nothing stored — consistent with readOnlyHint/idempotentHint.

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 packs returns, constraints, and the remote-storage note economically. The middle clause is dense and reads as a run-on, but essentially every sentence carries actionable information for a schema-heavy 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 nested-schema tool with no output schema, the description supplies the missing return-value picture and the safety/legal caveats. Only minor gaps remain (e.g., prerequisites for classification by plan type are left to the schema).

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?

Top-level coverage is effectively absent per the signal, but the description compensates by mapping the three pay-plan variants and the placeholder mechanism for ownContract. However, it adds little on today, classification, or the trigger conditions for candidate/startDate/offerExpiresAt beyond the schema's own nested descriptions.

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 (fill rolefig's California starter offer letter and pay plan) and enumerates the three supported plan types (commission, salary with bonus, hourly) plus the own-contract placeholder mode. An agent immediately knows this produces an offer/pay document, which none of the sibling job-search tools do.

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 clear operating rule ('Use only confirmed values and never invent terms') and distinguishes the two modes (rolefig template vs. the employer's own contract via {{placeholders}}). It doesn't frame when to prefer this over any sibling tool, but the 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?

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety bar is covered. The description adds real value beyond that: pagination mechanics and the fact that results carry the company's application URL plus a rolefig page, with no application submission. No rate limits or result-size behavior are 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?

Two dense sentences that are front-loaded with the core action and then the filter/paging mechanics. Every clause maps to a parameter or behavior, though the long filter list reads as a run-on that could be broken for scannability.

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 11 optional params and no output schema or schema descriptions, the description adequately covers filtering, sorting, paging, and the notable fields in the returned openings. The gaps (default/max limit, cursor naming consistency between 'after' and 'nextCursor') are minor but real.

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 0%, so the description carries the full param burden and does so well: it decodes q, workplace, employment type, country as ISO code, region as a code like CA, company slug, postedWithin (7 or 30 days), minPay as minimum annual USD, sort values, and the after cursor. It omits limit (default 50, max 100) and slightly narrows postedWithin to '7 or 30' though the schema accepts any number.

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 current openings) and clarifies scope: 'across every company,' which implicitly contrasts with list_company_openings. However, it never names or rules out the close sibling demo_search_jobs, so an agent must infer which search tool to pick.

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 clear operating context: what can be filtered, how to sort, and how to page (repeat the search with nextCursor as after). It also sets a boundary by noting rolefig never submits applications. It stops short of explicit when-not guidance or routing to get_job/list_company_openings.

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