company-signals

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

With no annotations, the description carries the full behavioral burden, and it usefully discloses the auth trait ('No key needed'). But it says nothing about return format, whether counts are scoped/cached, or rate limits, leaving meaningful gaps for a zero-param metadata endpoint.

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 compact sentence front-loads what is measured and appends the auth fact. Nothing is wasted, though the phrasing is slightly run-on and could be tightened.

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 no-param stats tool with no output schema, the description tells the agent what is counted and that no key is required. It is nearly complete; only the return shape/format is left implicit.

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 the baseline is 4; there is nothing for the schema to document and the description correctly conveys no inputs are required.

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 the concrete resource: counts of tracked companies/careers boards and days captured. This distinguishes it from the operational siblings (get_company_open_roles, get_hiring_changes, request_api_key), though the terse name 'coverage' alone would be ambiguous. No explicit sibling differentiation, so a 4 rather than 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?

'No key needed' implies this is a free introspection/stats tool usable before authentication, which gives some selection context versus the key-gated siblings. However, there is no explicit statement of when to call this versus alternatives or what question it answers for an agent.

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

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

With no annotations, the description carries the full burden and mostly succeeds: it discloses a rate limit (300 calls/day), a free API-key requirement, the data provenance (AI-compiled from public careers boards), an accuracy caveat (not human-reviewed) and a removal policy. The read-only nature is only implied by 'history'/'open roles', which is the one substantive 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, correctly front-loaded with what the tool returns before prerequisites and caveats. Slightly dense (multiple clauses per sentence), but no filler and 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 usefully summarizes the return shape (per-day, per-department counts plus source board), covers auth and rate limits, and flags data-quality limitations. The missing piece is routing guidance against sibling tools, which leaves a modest gap for a single-parameter 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 single 'host' parameter is documented in the schema with format guidance ('no www', example domain), so the description adds no parameter detail. Baseline 3 is appropriate when the schema fully carries this load.

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 ('Daily history of open jobs for one company') plus the returned granularity (count per day, per department, source board). It does not name or contrast with siblings like get_hiring_changes or coverage, so an agent can identify what it does but not trivially separate it from adjacent tools.

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

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

No when-to-use guidance is given, and no alternative tool is named despite three plausible siblings (get_hiring_changes, coverage, lookup_company_free) that an agent would need to disambiguate. The API-key prerequisite is stated, but that is a prerequisite, not usage direction.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses auth requirements and a rate limit (300 calls/day) and data provenance/quality caveats ('Compiled by an AI from public careers boards, not human-reviewed; removal on request'). It stops short of describing error handling or what an out-of-range day returns.

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 compact sentences, with the core output description front-loaded and the key/rate-limit and provenance caveats following. No wasted words.

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, yet the description conveys what comes back (company list with change size, sorted descending) and covers auth and provenance. Remaining gaps are minor — error behavior and result format details are unspecified.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (day format, series start, min_delta default). The description's 'largest change first' hints at ordering relative to min_delta but adds no syntax or format detail beyond the schema. Baseline 3 is correct.

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 whose open-job count changed on a given day — plus scope (a given day), direction (hiring more or cutting roles), and ordering (largest change first). It is clearly distinguishable from siblings like get_company_open_roles (single-company detail) and coverage.

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 prerequisite ('Needs a free API key (300 calls a day)') and implies a day-based lookup, but never states when to prefer this over siblings such as get_company_open_roles or coverage, nor any when-not conditions. 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?

With no annotations, the description carries the full burden and does so well: it discloses the rate limit (10 calls/day per caller), that no API key is required, the data provenance ('compiled by an AI from public careers boards, not human-reviewed'), a removal path, and that the 7-day change only appears 'once the series is long enough' (i.e., conditionally null output). It stops short of covering caching/freshness or error 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?

The value proposition is front-loaded in the opening question, followed by constraints and provenance in a tightly packed second sentence. Every clause carries information, though the density is high and the run-on structure slightly impedes scanning.

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

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

For a single-parameter, no-output-schema, no-annotation tool, the description supplies the key missing context: what the response contains (tracked status, today's count, 7-day delta when available), access constraints, and data reliability caveats. Structural details of the response and freshness semantics of 'today' remain unspecified.

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% — the single 'host' parameter is documented with format (no www) and an example. The description refers to 'this company' but adds no syntax or format meaning beyond what the schema already provides, 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?

The description clearly states the tool's function — returning a company's current open-role count plus a week-over-week hiring direction — framed as the question it answers. The verb+resource is discernible despite the interrogative phrasing. It does not, however, name or distinguish itself from siblings like get_company_open_roles or get_hiring_changes, which cover overlapping ground.

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 context is implied rather than stated: 'Free sample, no API key, 10 calls a day per caller' signals this is the low-commitment entry point, but the description never says when to prefer it over get_company_open_roles, get_hiring_changes, or request_api_key. No exclusions or alternatives are named, leaving the agent to infer routing from the siblings' names alone.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses the free-tier quota, the one-time link-opening flow, and the follow-up step of setting the key as the x-api-key header — useful operational context beyond the schema. It doesn't state whether emails are rate-limited, what happens on invalid emails, or delivery guarantees, keeping 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?

Two tight sentences, front-loaded with what the tool does and followed by the required interaction flow. 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?

Covers purpose, the email prerequisite, delivery mechanism, and post-request usage. With no output schema, it adequately explains what the user receives (the link/key). Minor gaps are error handling and whether the key is scoped to the connection.

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 email parameter is documented. The description reinforces that the email is where the key is sent and that it must be collected from the user first, adding slight semantic value beyond the terse schema field description.

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 (email) and resource (free API key link) with the quota detail (300 calls/day), making the purpose unambiguous and distinct from sibling lookup tools.

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 instructs the agent to ask the user for their email first, giving clear sequencing guidance. It doesn't name alternatives or specify when not to use this tool, 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.