arkerah

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

With destructiveHint=true and readOnlyHint=false declared, the description adds materially: nothing is persisted until the person confirms, unless assistants are permitted to make changes without asking, in which case it is saved immediately and the result says so. That two-phase, conditional-write behavior is not derivable from the annotations. It does not address reversibility or any permission model beyond the auto-apply exception.

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?

Purpose and the person's-own-words constraint are front-loaded, followed by the confirmation semantics; every clause carries information. The sentence is long and stacks multiple parentheticals, which slightly hurts scanability, but there is no filler.

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

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

For a single-parameter mutation with no output schema, the description covers the essentials: what is proposed, who confirms, and when the change actually lands (including the auto-save branch). It does not describe what a rejected or pending proposal looks like, but the 'result says so' note partially covers the return 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: the statement must be in the person's own words and represents what is true about them, illustrated with two contrasting example statements. This clarifies the expected phrasing and correction-vs-addition intent beyond the schema's 'What is true about the person, in plain words.'

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 precise verb plus resource: propose a correction to something arkerah holds about the person, or add something new, in their own words. Concrete examples ('I speak Dutch fluently', 'I am junior, not senior') make the scope unambiguous, and the 'propose' framing separates it from read-oriented siblings like what_you_know_about_me.

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?

Clearly conveys the context of use: it is for changing or adding facts about the person, in their own words, and spells out the confirmation-then-save flow including the auto-apply exception. It does not explicitly name an alternative tool (e.g., reading facts via what_you_know_about_me) or state when to avoid calling it, so it stops short of full when-not guidance.

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 and openWorldHint=false, so the safety profile is covered. The description adds that the result is a count-per-place projection of the person's own job data, but says nothing about failure modes, empty results, or how the numbers are keyed.

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?

Purpose is front-loaded in the first clause, and the two parameter sentences are dense but each carries real information. The single run-on sentence is slightly harder to parse than it needs to be, but there is no filler.

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

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

For a two-parameter, no-output-schema tool, the description covers the default level and the level/place dependency, which is what an agent needs to invoke it correctly. What the returned counts are keyed by (place names vs codes) is left implicit, which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse field notes by explaining the hierarchy: `place` narrows to 'the place one level up', with concrete examples (a country ISO code to count by region, a province to count by city). That relational rule is genuinely useful and not derivable from the schema alone.

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 (count) and resource (the person's jobs) with an explicit scope (per place), and the phrase 'the numbers on the map' conveys the aggregation intent well enough to separate it from search_jobs. It never names a sibling as the alternative though, so differentiation is inferred rather than stated.

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 prescribed: the agent can infer this is for aggregate counts rather than listing individual jobs, and the default ('country by default') is given. There is no explicit 'use this when you want totals, use search_jobs when you want the jobs themselves' 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 only flag readOnly=false, destructive=true, idempotent=false. The description adds substantial context beyond that: this is a two-phase proposal, nothing mutates until user confirmation, an exception exists for users who pre-authorize assistant changes, and the result text reports which path was taken. No contradiction with destructiveHint=true.

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 action and the input source, and the second sentence spends its length on the non-obvious confirmation semantics rather than filler. 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?

For a destructive, one-parameter mutation with no output schema, the description covers the trigger, the confirmation gate, and result reporting. It is only slightly short of complete because it never states the effect is reversible (via show_company_again), which matters for a destructiveHint=true 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 description coverage is 100% and the single parameter already documents 'A postingId from search_jobs, at the company to hide.' The description restates the same sourcing and the indirect company identification, adding no extra format, validation, or edge-case guidance, 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+resource ('Propose to stop showing the person jobs from one company') and clarifies that the company is identified indirectly via a job posting. This clearly separates it from the inverse sibling show_company_again and from read-only lookups like job_details or search_jobs.

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 context: the tool proposes a change, and that change only takes effect after the person confirms in support chat unless their settings allow automatic changes. It does not explicitly name show_company_again as the way to undo, so the alternative-routing is implied 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=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context by listing what the response contains (full advert text, requirements, optional salary, link), which is helpful given there is no output schema. It does not cover error behavior or missing-posting handling.

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 sentence, front-loaded with the input and scope, followed by a colon-separated list of return contents. Every element earns its place with no redundancy.

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 low-complexity, one-parameter read tool, the description is complete: annotations carry the safety profile, the schema documents the sole parameter, and the description covers return values in the absence of an output schema. Nothing essential 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 description coverage is 100% and the single postingId parameter is documented in the schema as 'The postingId search_jobs returned.' The description reinforces the same source but adds no format or syntax beyond what the schema already provides, so the baseline of 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 resource ('one job'), the key input ('postingId'), and enumerates the return payload (full text, requirements, salary, link). The reference to 'from search_jobs' distinguishes it from the sibling search_jobs tool, so an agent can tell what it does 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 context by noting the postingId comes from search_jobs, which implies the workflow prerequisite. It does not explicitly state when not to use it or name alternative siblings (e.g., correct_fact, why_not), so it stops short of full routing guidance.

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 and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior: it discloses the returned fields (title, company, city, rank, posted date, LinkedIn link) and the coupling requirement between place and level, which is more than the annotations provide.

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 resource definition, then the filtering rule, then the return shape. Mostly tight, though the 'same list the arkerah map shows' clause is a bit of scene-setting that doesn't carry invocation weight.

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 properly compensates by enumerating the returned fields, and all three parameters are documented. Nothing critical is missing, though it could note the default result count behavior for the unfiltered case.

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 place, level and limit are already documented with examples and defaults. The description reinforces the place+level coupling and restates the ISO-code example, adding slight clarity but little that is not already in the schema – 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 names a concrete resource – the person's own ranked job list – and ties it to a known artifact ('the same list the arkerah map shows'), which clearly distinguishes it from siblings like job_details (single job) or count_jobs (aggregate). The verb is implicit rather than stated, but the retrieval purpose is unambiguous.

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 real usage rule: filter by place only when place and level are supplied together, otherwise return all jobs with a known town. However, it never names or contrasts against the obvious alternatives (job_details, count_jobs), so the agent must infer routing from the sibling 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?

Beyond the annotations, it discloses the key behavioral trait: nothing changes until the person confirms in arkerah's support chat, unless assistants are permitted to act without asking, in which case it executes immediately and reports so. That conditional execution path is exactly the context annotations cannot convey, and it is consistent with readOnlyHint=false and destructiveHint=false.

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

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

Three sentences, purpose front-loaded, and every sentence carries information. The final sentence is a long compound clause that could be tightened, but 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 one parameter, full schema coverage, and no output schema, the description covers what an agent needs: what the tool proposes, how to name the company, and the confirmation/auto-execute flow. It leaves unstated what happens to an unconfirmed proposal, a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'Name the company as they hide it' tells the agent to use the person's own hidden-side naming rather than an arbitrary or canonical 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?

The description names a specific verb-plus-resource: proposing to re-show jobs from a company the person hides. It is clearly the inverse of hide_company, so an agent can place it among siblings, but it never names hide_company or any other sibling explicitly to sharpen the distinction.

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 clear: this is for companies the person has hidden and wants shown again. It gives no explicit when-not-to-use guidance and does not name alternatives, so it stops short of the top tier.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the result is grouped by topic and each item is tagged as stated, document-read, or inferred, which tells the agent how much to trust each fact.

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 the resource named first, followed by the grouping and provenance details. The parenthetical topic list is slightly long but each item aids recognition, and there is no filler.

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

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

With no output schema, the description must convey what comes back, and it does so at a conceptual level (per-topic grouping plus provenance). It stops short of describing volume, format, or empty-state behavior, but for a zero-parameter read tool it is largely sufficient.

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, which is the baseline-4 case. The description appropriately spends no words on inputs and instead describes the output content.

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 clear resource ('everything arkerah currently holds about the person') and adds structure detail (grouped by topic) plus a provenance dimension. It's specific enough to distinguish from siblings like correct_fact or search_jobs, though it never explicitly names them.

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 no when-to-use guidance, no prerequisites, and no mention of alternatives such as correct_fact for amending a stored fact. The usage is only inferable from the content description, which is a clear gap for an agent choosing among seven siblings.

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 and openWorldHint=false, so safety is covered. The description adds real behavioral value by enumerating the filter categories that cause exclusions, telling the agent what kind of diagnosis to expect. It does not describe the shape of the returned diagnosis beyond that.

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: the diagnosis first, then how to phrase the input with a concrete example. No filler, and the most important information is 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 must imply return content, and it does so well by naming the excluded jobs and the blocking filters. Minor gap: it never explains when the optional 'place' parameter kicks in or how a missing place is resolved.

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 'question' and 'place' are already documented; the description only reinforces 'plain words' and supplies an example query. It adds marginal meaning beyond the schema, so the baseline of 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 and unusual capability: it returns the jobs a person is NOT shown and names the personal filter (languages, level, education, eligibility, excluded companies/industries, role kinds) blocking each. That is clearly distinguishable from search_jobs and count_jobs, which only find or tally jobs.

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 purpose statement plus the worked example ('sales jobs in Amsterdam') makes the triggering scenario obvious to an agent. It stops short of naming alternatives (e.g., use search_jobs to actually list jobs) or stating when not to use it, so it is clear context without explicit routing.

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