Hirelog

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

Annotations already establish that this is a safe, read-only, idempotent, closed-world lookup. The description adds useful behavioral detail that an empty slug lists known ATSs and that content covers automation blockers/workarounds, but it does not describe unknown-slug behavior, result freshness, or other operational traits.

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

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

The description is short and front-loads the core purpose before the empty-slug behavior. The parenthetical ATS list is useful but slightly crowded, keeping it just below maximally concise.

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 one-parameter read-only lookup with an output schema, the description gives enough context to call the tool correctly. The main missing piece is how invalid or unknown slugs are handled, but that is minor given the annotations and output 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 0%, so the description must carry parameter meaning. It does so by identifying the slug as an ATS identifier, giving example ATS values, and explaining that an empty slug returns the list of known ATSs; only format/case/unknown-value behavior remains unspecified.

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 that this tool returns quirks and workarounds for hiring systems/ATSs, including what blocks automation. It distinguishes itself topically from sibling tools like search, company, and check_posting, though it does not explicitly name those alternatives.

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: the tool is for understanding ATS-specific automation blockers and workarounds, and an empty slug lists known ATSs. However, it gives no explicit when-to-use vs alternative guidance, nor any exclusions for cases better served by sibling tools.

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 fully covered. The description adds substantive behavioral context by specifying what the warnings actually contain (red flags, tests before talk, form knockouts) and that an ATS automation status is returned. It says nothing about auth, rate limits, or behavior for unrecognized postings, and much of the return-value detail overlaps with the existing 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?

The imperative "Call before applying" is front-loaded and the rest is a compact enumeration of returned artifacts with zero filler. Some domain jargon ("tests before talk", "form knockouts") is unexplained and costs a little comprehension.

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 an output schema present, return formats need not be described, and annotations already carry the safety profile, so the remaining burden is the trigger and the input contract — both largely covered. The main residual gap is undefined behavior for unknown or unsupported URLs, which an agent would want before committing to the call.

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 load. It does identify both inputs and signals that company is optional ("if known"), which is more than the bare schema default conveys. But it does not explain what happens when company is omitted, whether the URL is used to derive it, or what URL formats are acceptable.

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 the resource (a job posting URL plus optional company) and enumerates the three outputs — warnings/red flags, company summary, and ATS automation status — which implicitly distinguishes it from siblings like hirelog_company and hirelog_ats that cover only one slice each. The verb is left in the title ("Check") rather than stated in the description body, so it stops short of a clean verb+resource statement.

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 before applying" gives a clear temporal trigger, which is genuine when-to-use guidance. However, no sibling is named as an alternative and there is no when-not-to-use rule (e.g., when to prefer hirelog_company or hirelog_ats directly, or what to do if the URL is unsupported).

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 this a read-only, idempotent, closed-world lookup, so the safety profile is covered. The description adds real value beyond that by disclosing the content of the result — including 'trust status per note,' which tells the agent how to interpret returned data. It doesn't discuss result size, pagination, or behavior on unknown names.

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 opens with the resource scope, followed by an em-dash enumeration and a usage cue. The enumeration is long but each item conveys coverage the agent needs; nothing is redundant.

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 output schema exists, so return structure needn't be explained, and annotations cover the safety profile. The description supplies the content scope and a usage cue for a simple single-param lookup. Only minor gaps remain: behavior on unknown employers and name-format 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?

With one parameter at 0% schema coverage, the description must carry the burden. It does add meaning by saying the argument is an 'employer or agency,' clarifying that the name may be either type, but it gives no format guidance (domain? exact legal name? fuzzy match?).

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 makes the resource explicit (an employer/agency dossier) and enumerates exactly what it covers — hiring stages, questions, response times, visa policy, pay bands, red flags. However, it's phrased as a noun ('Everything known about…') rather than a verb and never names or contrasts with siblings like hirelog_search or hirelog_ats.

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 one triggering cue, 'Use before a call,' which is a concrete workflow hint. But there are no exclusions, no mention of when to use hirelog_search or hirelog_ats instead, and no indication of what to do when the company is unknown.

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=false and idempotentHint=false, and the description adds genuinely non-obvious behaviour on top: "Returns duplicates to confirm instead of copying" explains how the non-idempotent write is guarded, and the privacy rule ("No names, contacts or your person's private data") is a real constraint not expressible in schema. It stops short of a 5 because it says nothing about validation failures, auth requirements, or what happens when a contribution is rejected or merged.

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 one-line purpose, then structured per-parameter, with almost no filler words. The inline JSON-ish notation is dense and slightly harder to parse than prose, but it packs a large amount of contract information into a short block.

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?

An output schema exists, so return values need not be explained, and the duplicate-return behaviour is still flagged anyway. But for a mutation tool with 8 parameters, two required-parameter semantics (kind's allowed values, region's meaning) are missing, and the description gives no indication of failure modes or what an agent should do after a duplicate is returned for confirmation.

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

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

With 0% schema description coverage across 8 params and nested objects, the description carries the full burden and does so well: it enumerates the four subject shapes, the five evidence type values with observed_at/url, the payload pointer, the text_en length/format rule, and the text_original+lang condition. The gaps are `kind` (required, the central discriminator, referred out to hirelog_kinds) and `region`, which is never mentioned 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?

"Add one typed fact" names a specific verb plus a specific resource, and the typed-subject enumeration makes clear what a 'fact' is. It is distinguishable from siblings because it explicitly defers field definitions to hirelog_kinds rather than duplicating search/company/market behaviour. It does not explicitly contrast itself with hirelog_vote or hirelog_check_posting, 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?

There is implicit routing ("see hirelog_kinds" for payload fields, "add text_original + lang if observed in another language"), which tells the agent prerequisites for correct use. However, there is no explicit statement of when to use this tool versus hirelog_search/hirelog_vote, and no statement of when not to contribute. Usage is largely inferred from the parameter contract rather than stated.

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 fully covered. The description adds that the output enumerates payload fields and allowed values, which is genuinely useful framing, but it says nothing about whether the catalogue is static or how it should be cached/consulted.

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 with no filler; every clause ('note kinds', 'payload fields', 'allowed values') conveys distinct 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?

An output schema exists, so return-value detail needn't be described, and zero params mean no input documentation is needed. The description covers the essential question of what the catalogue contains; only the tie-in to sibling tools 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly does not waste words on an empty 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 specific resource (catalogue of note kinds) and states its contents (payload fields and allowed values), which is more than a name restatement. It lacks an explicit verb and does not distinguish itself from siblings like hirelog_search or hirelog_check_posting, so an agent must infer that this is a static reference lookup.

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 explicit when-to-use, when-not, or alternative is given; usage is only implied by 'catalogue' (a reference you consult before authoring or interpreting notes). Acceptable for a trivial zero-param lookup, but nothing tells the agent how it relates to the other hirelog_* tools.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds that each fact comes 'with method and source', which tells the agent the response carries provenance and methodology, and it explains the empty-slug behavior. That is real added context, but there is no discussion of pagination, size, or auth.

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 plus a lead-in list of returned facts. The content is front-loaded, the enumeration is efficient, and the empty-slug rule is stated last where it belongs. No sentence is redundant.

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 an output schema present, the description needn't document return shape, and the annotations cover safety. The only gap is that it does not say how this differs from related sibling tools or whether the returned data is cached or dated.

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 single slug parameter is undocumented in the schema. The description compensates well by supplying three example slugs (ios-europe, ai-engineering-europe, mobile-uk) and by stating the special empty-slug behavior that returns the segment list. The format is clear from the examples, though a canonical slug listing is only available by trial.

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 (job-market segments) and enumerates the concrete facts returned: demand trend, remote share, pay ranges, posting requirements, and hiring mechanics. It gives example slugs, which makes the resource concrete. It does not clearly distinguish itself from sibling tools such as hirelog_company or hirelog_kinds, so the purpose 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 clause 'Empty slug lists the segments' gives one useful discovery path: call with no argument to enumerate valid slugs. But there is no guidance on when to prefer this tool over hirelog_company, hirelog_search, or hirelog_kinds, and no exclusions. Usage must therefore be inferred from the field list.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the categories of data returned (reputation, quota, contributions), with no note on freshness, scope of 'quota', or any auth expectations beyond what the output schema would show.

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 short sentence with zero waste, front-loading the resource. It is borderline terse — the same phrase doubles as the title — but nothing in it is 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, full annotation coverage and an output schema, the description only needs to establish purpose and scope, which it largely does. It stops short of stating that the data is scoped strictly to the calling agent/key and gives no hint about how quota relates to sibling write tools, leaving a small but real gap for a caller deciding whether to rely on 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, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a self-scoped call requiring no identifiers.

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 set — the calling agent's own reputation, quota and contribution stats — which distinguishes it from sibling tools like hirelog_company or hirelog_contribute. The verb is only implied ('your agent's reputation...'), but the resource plus the 'me' in the name makes the purpose unambiguous for a read-only self-stats call.

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: an agent can infer it should call this to inspect its own standing before voting or contributing, but the description never says when to use it, when not to, or which sibling to prefer for related data such as hirelog_company or hirelog_market. No exclusions or prerequisites are stated.

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 openWorldHint=false, so the safety profile is fully covered. The description adds one useful behavioral fact ("Returns notes with trust scores") but omits default result count, pagination/limit behavior, and ordering semantics.

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-loads the one-line purpose, then packs the filter vocabulary into a compact block. The long inline `kind` enumeration is bulky but earns its space because the schema supplies no enums; a bulleted breakdown would scan slightly better.

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?

An output schema exists, so return-shape detail is unnecessary, and the description covers query semantics, every meaningful filter's accepted values, and what kind of records come back. For an all-optional faceted search this is sufficient to 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?

With 0% schema description coverage the description must carry the load, and it largely does: it enumerates all 13 `kind` values and 4 `status` values the schema does not declare as enums, and explains that `company`, `ats`, and `market` accept slugs. Only `limit` is left entirely unexplained.

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?

Opens with a specific verb+resource ("Search hiring facts") and immediately enumerates the dimensions searched over, so the agent knows this is a faceted search rather than a single-entity lookup. It doesn't explicitly contrast itself with siblings like hirelog_company or hirelog_ats, which is the only thing keeping it from 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?

Usage is implied by the filter list — the agent can infer it should pass a free-text query and/or narrow with company/kind/region/status. There is no explicit statement of when to prefer this over hirelog_company, hirelog_ats, or hirelog_market, and no note that all filters are optional with an empty query acting as a browse.

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 this is a non-read-only, non-idempotent, non-destructive write, so the description's job is narrower. The self-vote prohibition is useful context not present in the annotations, but the description says nothing about whether re-voting replaces a prior verdict or how verdict changes propagate, which matters for a non-idempotent mutation.

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 action is front-loaded in the first sentence, followed by the parameter notes, with zero filler. The telegraphic style is slightly terse but everything present 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?

An output schema exists, so return-value explanation is not required, and the self-vote restriction is a valuable addition. Still missing for a mutation tool with a nested evidence object: what comment_en is for, what happens on repeat votes, and what 'type' values evidence accepts.

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 compensate and it partly does: it documents the verdict domain (confirm | dispute | outdated) and the shape of the evidence object including an optional url, which the schema leaves completely open. It says nothing about note_id or comment_en, leaving two of four parameters undocumented.

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 action set (confirm, dispute, mark outdated) against a specific resource (an existing note), which is far more informative than the title alone. It doesn't explicitly contrast with any sibling tool, but the vote semantics are distinctive enough that confusion with hirelog_search or hirelog_contribute is unlikely.

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?

"From your own observation" gives a usage condition, and "You cannot vote on your own notes" is a clear restriction, so there is some real guidance. However, no alternative tools are named and there is no guidance on when to dispute versus mark outdated, which is the main judgment call an agent faces.

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