JobSlop

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that this returns a single listing's full text with specific fields, which is useful, but it says nothing about failure behavior for an unknown/expired id or any rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that names the resource, the key input, and the payload contents with zero filler. 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?

With no output schema, the description usefully enumerates what comes back (status, dates, reposts, ghost-job flag, description), which an agent needs. It is nearly complete for a one-id read tool, missing only error/edge-case behavior for invalid ids.

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 a single parameter with 100% schema description coverage ('An id from search.'), so the schema already carries the semantics and a baseline of 3 applies. The description restates that the id comes from search but adds no format, length, or validity details beyond the schema.

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

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

The description states a specific verb+resource: retrieving 'full text for one listing id' and enumerates the returned fields (status, dates, reposts, ghost-job flag, description). It routes back to 'search' as the source of the id, but never distinguishes itself from the near-identical sibling jobslop_get_job, leaving ambiguity between the two.

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: the id must come 'from search,' so an agent can infer this is the follow-up detail call after a search. However, there is no explicit when-to-use/when-not guidance and no mention of when to prefer jobslop_get_job, jobslop_find_job_by_url, or the bare 'search' 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the report's ordering rule (ghost-flagged and longest-open first) and which figures it aggregates. It stops short of describing pagination or freshness of the tracked data.

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-loaded with the resource and then the contents. Every clause carries information, though the parenthetical ordering note sits at the end rather than being surfaced earlier.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of conveying the return shape, and it does so: counts by status, flagged share, and an ordered listing list. Combined with 100% schema coverage for pagination and status filtering, an agent has enough to call and interpret it, though result paging behavior is left entirely 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?

Schema description coverage is 100% (limit, offset, status, company all documented in-schema), so the baseline is 3. The description only echoes the per-company scope and the active/inactive/ghost framing, adding no syntax or filtering detail beyond the schema.

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

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

Names the resource (one employer's tracked listings) and enumerates what the report contains: counts of active/inactive/ghost-flagged listings, the share flagged, and the listing set itself. An agent can tell this is a per-company aggregation report rather than a raw search or index overview, though it never explicitly contrasts itself with siblings like jobslop_list_companies or jobslop_index_overview.

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 "one employer's" implies this is the tool to pick once you have a specific company, versus list_companies for discovery, but no when-to-use or when-not-to-use condition is stated. Usage is inferable from scope, not spelled out, and no alternative is named.

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

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

Annotations already declare readOnly/openWorld=false/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond them: the tool is a lookup that may find nothing (the 'if so' branch) and returns a status plus a ghost-job flag rather than a full posting. It stops short of defining what status values mean.

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. The capability statement comes first and the usage trigger second, which is the right front-loading for a lookup 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?

With no output schema, the description carries the return-value burden and handles it: it says what comes back (status, ghost-job flag) and that a miss is possible. It could be more complete by naming the possible status values or how an untracked URL is signaled, which matters for a single-parameter tool whose whole purpose is a yes/no-plus-flag answer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'url' parameter is documented there with format, length bounds, and an example. The description only restates 'a given URL' and adds no syntax, canonicalization, or matching rules beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Check whether JobSlop tracks the job posting at a given URL') plus the payload it returns ('status and ghost-job flag'). This distinguishes it from siblings like jobslop_get_job and jobslop_search_jobs, which are not URL-keyed lookups.

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 triggering context: 'Use this when someone shares a job link and asks whether it is a ghost job.' It names the input shape and the user intent, though it never explicitly contrasts with jobslop_get_job or jobslop_company_report, so sibling routing is left partly to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the returned content (dates, 30-day sightings, reposts, plain-language ghost-job flag, description text), which matters because there is no output schema. It does not cover failure behavior for an unknown id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence: purpose first, then the payload it returns. Dense but every clause carries information; only minor tightening (e.g. the long colon list) would improve it.

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 carries the burden of describing the return payload, and annotations handle the safety semantics. What is missing is error/edge behavior (invalid or stale id, sightings window semantics), which would be needed 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?

Schema description coverage is 100% and both parameters are self-documented, including the id provenance and the 8000-character trimming of include_description. The description adds essentially nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (get full detail for one listing) and pins the key ('by its JobSlop id'), which implicitly distinguishes it from jobslop_find_job_by_url and jobslop_search_jobs that take other keys. It also enumerates what the detail contains, so an agent knows exactly what it is fetching.

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 id parameter description says the id comes from jobslop_search_jobs or jobslop_find_job_by_url, so the flow is inferable. But the description itself never states when to call this versus those siblings, nor any preconditions or 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value beyond that: it discloses that the result is a point-in-time snapshot ("when the index was generated") and describes coverage scope, which is exactly the staleness context an agent needs before trusting downstream queries.

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. The content of the response is front-loaded and the usage directive follows immediately, so an agent can act after one read.

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 and no output schema, the description carries the return-value burden and does so by listing the exact metrics returned plus the generation timestamp and coverage. Nothing needed to call this tool 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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly avoids inventing filter arguments, and the enumerated return fields implicitly confirm this is an unfiltered snapshot.

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 (the JobSlop public index) and enumerates exactly what the tool returns: job totals, active/inactive/ghost-flagged counts, company counts, generation time, and coverage. This clearly separates it from siblings like jobslop_search_jobs, jobslop_get_job, and fetch, which operate on individual records rather than the index as a whole.

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?

"Call this first to see how fresh and how large the data is" gives explicit when-to-use guidance and even a sequencing hint relative to other tools. It stops short of naming alternatives or stating when-not to call it, so it is clear context rather than full routing logic.

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 that results carry listing counts and can be ordered by ghost-flag metrics, which is modestly useful, but it says nothing about paging behavior or the fact that offset descriptions reference a next_offset with no output schema defining it.

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 padding, and the resource/return summary is front-loaded before the filtering options. It is efficient but very terse, offering no structural cues beyond the two clauses.

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 is the only place to learn the return shape, and it gives just 'listing counts' without mentioning pagination fields. The schema's offset text promises a next_offset from the previous page that is nowhere defined, leaving the agent's paging loop underspecified.

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 80%, so the schema carries most parameter documentation; the description only loosely glosses 'filter by name' (query) and 'sort by size or ghost-flagged' (most_jobs/most_ghosts/ghost_share). It does not clarify the distinction between most_ghosts and ghost_share or the role of min_jobs, so it sits at the expected 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?

States a specific verb and resource ('Companies in the JobSlop index') plus the returned payload ('with their listing counts'), which is more than a restated title. It does not name any sibling, so an agent can't tell from the text alone why it should pick this over jobslop_company_report.

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

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

Usage is implied by 'Filter by name and sort by...', which suggests this is the browse/enumerate tool, but there is no explicit when-to-use, when-not, or pointer to jobslop_company_report for per-company detail or jobslop_search_jobs for listings.

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), so the bar is lower. The description adds value beyond them by noting results are 'compact summaries with paging', which tells the agent the response is a paginated abbreviated view rather than full records.

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 the search scope front-loaded and the fallback route to the detail tool immediately after. 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 8 fully documented parameters, no output schema and no nesting, the description covers what an agent needs: what it searches, what comes back (compact, paged), and where to go for full detail. Return-field specifics are absent, but paging guidance offsets that.

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 every parameter is already documented in the schema with examples and enum meanings. The description only enumerates the facets (keyword, company, status, location, posting age) without adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (tracked US job listings) plus the filterable facets. It also distinguishes itself from jobslop_get_job by scoping itself to search and pointing to the sibling for single-listing detail.

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 jobslop_get_job when one listing's full detail is needed. It does not, however, clarify when to prefer this over jobslop_find_job_by_url or jobslop_company_report, so the alternative-selection guidance is only partial.

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 one genuine behavioral fact beyond annotations — that the result is a set of ids intended for fetch — but says nothing about result caps, ranking, or empty-result 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, zero filler, and the core action plus the downstream chaining hint are front-loaded. Nothing to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only search with no output schema, the description supplies what the schema cannot: the resource scope and the id-return contract that feeds fetch. Minor gap is any hint about result volume or pagination, but little else is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes slightly beyond the schema's single example by naming the semantic categories the free-text query should carry (role, company, location), which helps an agent compose a combined keyword string.

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 (tracked US job listings) plus the searchable facets (role, company, location). It is clear on its own, but it never distinguishes itself from the near-identically named siblings jobslop_search_jobs or search-like jobslop_find_job_by_url.

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?

Implied usage only: the phrase 'Returns ids to pass to fetch' tells the agent this is a first step in a two-call chain. However, with three search-flavored siblings there is no explicit when-to-use-this-vs-those guidance and no exclusions.

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