WorldRole

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely additive constraints: no profile writes, no sending, no monitoring, no live verification, and zero questions by default. That goes beyond the annotation set, though it omits what actually happens during the call or what state is returned.

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

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

Three short sentences with no padding, but the front-loaded sentence is abstract to the point of being hard to parse ("Restore known facts and plan useful work before asking") rather than stating the concrete action. Compact, but the density is obscurity rather than 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, an enum-driven workflow selector, and 0% schema coverage, the description must do more. It never says what a call returns, what each workflow value launches, or how `profile_state` affects behavior, so an agent cannot confidently invoke it for anything but a blind initialize.

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% across 4 parameters (including a nested AssistanceContext object), so the description carries the burden. It only vaguely glosses `assistance_context` ("describes actual task requirements and client checks, without private answers") and says nothing about `workflow`, `locale`, or `profile_state`, leaving the most important parameter 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?

The description says it restores known facts and plans work at session start, hinting at a pre-question warm-up step, but the verb+resource pairing is abstract ("boardwork_start" never named) and the central concept of launching a workflow (the `workflow` enum with six values) is not mentioned at all. An agent can guess this is an initializer but cannot tell how it differs from siblings beyond being first.

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?

"...before asking" and "Defaults to zero questions" imply the timing (start of interaction, prior to interrogating the user), which is real usage guidance. However, no alternatives are named, no conditions for when-not-to-call are given, and nothing explains which `workflow` value to pick or whether a later call supersedes this one.

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

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

Goes well beyond the annotations: discloses the 20-job bonus side effect, that the bonus is once-ever, that repeats return the same link without re-granting, and that no message is sent. This adds real call-time consequences on top of idempotentHint/destructiveHint.

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?

Four short sentences, front-loaded with the gating condition, then behavior, then edge cases. Every sentence carries 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?

Covers the gating condition, return value (public URL), side effect, idempotency and silence, with no output schema needing explanation. The only gap is the unexplained request_id parameter.

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% and the single required parameter, request_id (a uuid), is never explained in the description. The idempotency sentence hints that repeats are deduplicated but does not tie that behavior to request_id, so the agent must guess its purpose and format.

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 (create referral link) plus the concrete outputs: a public URL and the once-ever 20-job bonus. The scope is unambiguous and no sibling tool overlaps it.

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 states the trigger condition ('only when the user explicitly requests an invitation link') and three named exclusions (installation, startup, automatically after an exhaustion notice). Nothing is left 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 flag destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the description's job is to say what is destroyed and what remains — and it does: summary cleared, future saves paused, empty version marker retained, resumable later. It doesn't address whether current data is recoverable after the fact beyond the marker, but the disclosure is well above baseline.

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

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

Three short sentences, trigger condition front-loaded, then effect, then recovery path. No filler and no repetition of annotation or schema data.

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, no-output-schema tool the description covers trigger, effect, retention, and reversal, which is nearly everything an agent needs. The remaining gap is the unexplained required parameters, particularly the version precondition.

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

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

Schema description coverage is 0% for two required parameters. The description never mentions request_id (uuid) or expected_version (integer, min 0), so an agent gets no hint that expected_version is an optimistic-concurrency check that must match the current profile version. With zero coverage, the description needed to compensate and doesn't.

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 concrete verb chain (clear the career summary, pause future saves) and clarifies that the operation is a soft delete retaining an empty version marker, which resolves the ambiguity in the name 'delete_profile'. It also distinguishes the counterpart operation (update_profile with resume=True). It stops short of a full sibling comparison but the effect 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 an explicit trigger condition: 'when the user asks to forget or stop remembering', which is a strong when-to-use signal. It also describes the path back ('resume via update_profile'). It doesn't state when NOT to use it (e.g., partial clearing via update_profile), but the guidance is clear.

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 establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds some scope context by noting that only a few accepted roles are returned and that company-wide policies do not automatically apply to every role, but it does not disclose return format or evidence 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 description is short and front-loaded, with the core read operation stated first. The second sentence is somewhat cryptic, but it is not verbose and does add a cautionary note.

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 tool with three parameters at 0% schema description coverage and no output schema, the description is too sparse. It leaves include_evidence unexplained and gives no detail about what 'company identity' or 'accepted roles' actually contain. Annotations mitigate the safety gap but not the semantic gaps.

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 compensate. It vaguely maps to company_id and roles_limit through 'company identity' and 'a few accepted roles,' but it does not explain roles_limit defaults or maximum, nor does it mention include_evidence 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?

The description states a specific verb and resource: read company identity and accepted roles. It is clear what the tool returns at a high level, but it does not distinguish itself from the sibling search_companies tool or clarify the ambiguous phrase 'accepted roles.'

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 explicit guidance on when to use get_company versus search_companies or other sibling tools. The policy caveat is not usage guidance; it does not name alternatives, prerequisites, or exclusion conditions.

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, closed-world), so the bar is lower. The description adds meaningful semantics beyond them: that the payload carries cached links, relationship basis, timestamps and 'missing' checks, and that a not_available status is not evidence of closure. It still omits default section behavior and any limits on the response.

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 with no filler, but they lead with vague jargon ("verification includes cached links, relationship basis...") instead of the plain purpose. The most actionable line, the not_available caveat, is buried last.

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

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

For a read tool with no output schema and zero schema description coverage, the description should explain what comes back per section and the default scope. It instead offers hints about verification metadata and a status caveat, leaving the agent under-informed about the actual return shape.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. "Selected details" only faintly gestures at the sections parameter (requirements/salary/evidence/verification), and nothing explains job_ids expects up to 10 UUIDs or what happens when sections is null.

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?

"Read selected details" signals a read operation over job records, but it never states the resource plainly (jobs by ID) or what a 'detail' section contains. Nothing distinguishes it from the sibling search_jobs, so the agent must infer the lookup-vs-search split from the name alone.

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 operational guidance ("Use host search/browser to verify before acting", "not_available is not proof the employer closed the job") that shapes how the agent treats results, but offers no when-to-use rule and no routing versus search_jobs or the other 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 establish readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral guidance: empty fields indicate missing data and should not trigger a user form, and the tool never accepts another user 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?

The description is three short sentences with no wasted content. Purpose is front-loaded, followed by handling guidance and a scope constraint.

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 zero-parameter, read-only profile tool with no output schema, the description covers purpose, return summary, empty-field semantics, and access scope. Nothing essential for correct invocation 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 has zero parameters, so the schema baseline is already adequate. The description adds a relevant parameter-level clarification that no user ID is accepted, preventing attempts to pass one.

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

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

The description states a specific verb and resource: read/export the current account's compact career summary. It is clearly distinguishable from update_profile and delete_profile through 'Read/export' and 'current account', though it does not explicitly name sibling 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?

It gives clear usage context ('for conversational onboarding') and an important scope exclusion ('Never accepts another user ID'). It does not explicitly state when to prefer get_company/get_jobs or other alternatives, so it falls short of full alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral facts beyond that: calling it 'does not spend a job' (no quota consumption) and it is not auto-invoked at install/startup. It does not describe the shape of the returned usage figures, which is the remaining gap.

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

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

Three short sentences, front-loaded with the core action, then the invocation policy and the scope caveat. Slightly telegraphic phrasing ('Does not spend a job') but no wasted text.

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?

Low-complexity read tool with full annotation coverage and no parameters, so most requirements are met. However, there is no output schema, and the description never says what the usage report contains (limits, remaining counts, reset dates), leaving the agent to guess what comes back.

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 and the schema is an empty object, so there is no parameter semantics to explain. Baseline of 4 applies since there is nothing the description could usefully add here.

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 concrete verb ('Read') and resource ('current hosted account/guest allowance'), which maps cleanly onto the tool name get_usage. No sibling tool deals with usage/quota, so an agent can place it without ambiguity. The only weakness is the jargon 'allowance', which is not defined, but the intent (report current quota/usage) is recoverable.

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?

'when requested' plus 'No promotion at install/startup' gives both a positive trigger (on-demand) and an explicit anti-pattern (do not call automatically at startup). 'external free sources have independent limits' scopes the answer so the agent knows this covers only hosted usage. It stops short of naming a sibling alternative, but none competes.

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 bar is lower, yet the description still adds genuine context beyond them: an empty result means a corpus gap rather than a nonexistent company, and the tool does not resolve arbitrary URLs. That result-interpretation guidance is exactly what an agent needs to avoid false negatives.

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, with the primary capability front-loaded and the caveat appended. Every clause carries information an agent would otherwise have to guess.

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 4-param read-only lookup with annotations covering the safety profile and no output schema to explain, the definition is nearly sufficient. The remaining hole is pagination behavior (limit/cursor) and whether name matching is exact or fuzzy, which the description never addresses.

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 covers only two of four (name, and domain via "exact website hostname", where the exactness note is a useful addition). Limit (max 5) and cursor pagination are entirely undocumented, leaving the agent unable to page through results from text 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+resource ("Find known companies") and the two lookup keys ("by name OR exact website hostname"), which is enough to tell it apart from a singular lookup like get_company. It stops short of naming that sibling explicitly, so differentiation is implied 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?

The "exact website hostname" constraint and "never fetches arbitrary URLs" implicitly tell the agent this is a corpus lookup, not a live web fetch, and that a hostname must be exact. However, there is no explicit statement of when to prefer this over get_company, nor what to do when name and domain are both omitted.

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 read-only, idempotent, non-destructive, non-open-world, so safety is covered. The description adds real behavior beyond that: one role per company by default, and exclusions being applied before pagination (an ordering guarantee that matters for result counts). It still omits how preferences affect ranking, what cursor contains, and what each intent mode changes.

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, front-loaded with the core action and followed by the two most surprising defaults. No filler, though the scarce space is spent on defaults rather than on the schema semantics that are actually missing.

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 parameters, nested Filters/Preferences/Salary objects, multiple enums, no output schema, and 0% schema description coverage, this is a complex tool. A three-sentence description leaves an agent unable to populate most of the schema correctly, especially the intent and preference-weighting semantics that drive the ranking.

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 burden, and it does not. It gestures at 'filters', 'preferences', and 'exclusions' but never explains the distinctions between any_tags/required_tags/excluded_tags, required_skills vs skills preferences, the salary sub-object, mode, china, or the intent/cursor/count controls.

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

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

States a specific verb and resource ('Search a small page of sourced jobs') plus the axes it operates on (filters and weighted preferences). It does not differentiate from the sibling get_jobs, which an agent could easily confuse with this search tool.

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?

Phrases like 'small page' and 'weighted preferences' imply a relevance-ranked discovery use case, but the description never says when to use this versus get_jobs or search_companies. The intent enum (best_matches/discover_more/latest) that would express this choice is left unexplained.

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 declare non-read-only, idempotent, non-destructive; the description adds the real behavioral burden: omitted fields stay, null deletes, supplement on a populated field raises PROFILE_MERGE_REQUIRED and is atomic (nothing saved), retry must switch to compiled, no server LLM or pending queue, and no-ops don't bump version. That is far beyond what the annotations convey.

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?

It is front-loaded with the core mode distinction and every clause carries operational information, but the telegraphic semicolon-chained style packs several rules per sentence and makes it harder to scan than it needs to be. Length is reasonable for the complexity; readability is the cost.

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 versioned, atomic mutation tool with no output schema, it covers merge semantics, error path, idempotency, size limits, and evidence rules. It stops short of describing the success response shape or the full error taxonomy beyond PROFILE_MERGE_REQUIRED, which leaves a small gap for an agent handling failures.

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 carry everything, and it largely does: mode semantics, resume gating, request_id as an idempotency token, expected_version implied by conflict/re-read and version-bump rules, and patch value rules (<=500 chars, <=8 KB total) plus the meaning of the state enum values (user_reported, document_supported, needs_confirmation). Only minor gaps remain, such as the expected_version bump behavior on conflicting writes.

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?

'Save important career facts' plus the compiled/supplement mode distinction makes the verb and merge semantics clear, and 'Read first' implicitly points at get_profile. It never names a sibling explicitly, so an agent must infer the pairing with get_profile/delete_profile rather than being routed.

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 explicit conditions for the key decisions: compiled vs supplement, 'Read first', 'batch meaningful changes', 'Reuse request_id for identical retry', 're-read on conflict', and a hard exclusion for resume=True ('only on explicit request to resume paused memory'). The when-not guidance ('no full chats/files/secrets', 'never reconstruct deleted facts') is equally specific.

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