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

With zero annotations, the description carries the full burden and does so substantively: it discloses that no submission is transmitted, that a dry-run receipt is recorded, and that non-Greenhouse sources return held=true/transmitted=false with a hold_reason. It omits permission/auth requirements beyond 'owner' and says nothing about idempotency or repeat-approval 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?

Three sentences, front-loaded with the action, then branching behavior, then the overarching caveat. Dense but each clause adds information; the final 'transmits NOTHING' slightly restates the dry-run point but earns its place as the key safety fact.

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?

A single-parameter mutation with no annotations and no output schema gets a fairly complete picture: what happens per source, the shape of the held response, and the no-transmission guarantee. Missing error/failure modes and permission requirements keep it from being fully complete.

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 single parameter has 0% schema description coverage, so the description must compensate. It implies application_id refers to a prepared application, but never states the expected format or whether it is a tracker/job-scoped identifier. Marginal help over the bare 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?

States a specific verb and resource ('Owner approves a prepared application') and branches by source (Greenhouse vs any other). It is distinguishable from siblings like prepare_application and reject_application by the 'approve' verb and the 'prepared' precondition, though it never names those siblings directly.

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?

'prepared application' establishes the prerequisite that prepare_application must run first, and the closing 'v0.1 transmits NOTHING' plus the APPROVED-AND-HELD path tells the agent what this tool does not accomplish. No explicit when-not-to-use or named alternative, however.

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 must carry the full behavioral burden. It usefully discloses what gets destroyed (profile, policy, applications, cached jobs, receipts ledger) and that a confirmation flag is required, but it omits whether the purge is irreversible, what permissions are needed, and whether deletion is immediate.

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

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

Two tight sentences with the destructive scope front-loaded and the confirmation requirement immediately after. Every clause earns its place.

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

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

For a destructive single-parameter tool with no annotations and no output schema, the description covers scope and the confirm gate but leaves irreversibility and permission requirements unstated. Adequate but with clear gaps for a high-stakes delete operation.

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 does explain that 'confirm' must be true to proceed, which adds meaning beyond the bare boolean type, but it never states what happens when confirm is false or omitted.

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 ('purge') and enumerates exactly which resources are removed: profile, policy, applications, cached jobs, and the receipts ledger. No sibling tool performs deletion, so it is distinguishable, though the modifier 'verified' is left unexplained.

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 description gives no when-to-use guidance, no prerequisites, and no alternatives. 'Requires confirm=true' is a parameter constraint, not usage guidance about when this destructive operation is appropriate.

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, and the description does not disclose any behavioral traits such as read-only status, authentication requirements, or side effects. It only lists the data fields returned, which is minimal context.

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 extremely concise and front-loads the key data points without any wasted words. However, it is a fragmentary list rather than a structured sentence, which slightly reduces clarity.

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?

Given the tool's simplicity (no parameters, no output schema, no annotations), the description provides adequate information about what is returned. Yet it lacks any context about the tool's role relative to siblings or usage conditions, leaving it minimally complete.

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 schema covers everything. The description does not need to add parameter meaning, and the baseline score of 4 is appropriate.

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 lists the specific data points returned (current policy, pause state, today's submission count, submission mode), making it clear what the tool provides. However, it lacks an explicit verb and does not differentiate itself from siblings like set_policy or get_tracker.

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 guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. The implied usage as a getter is not made 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 provided, the description must carry the behavioral burden. It discloses the state values and refusal count but says nothing about read-only safety, side effects, authorization, rate limits, or whether refusal count is global or per application.

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 contains no filler, but it is a sentence fragment with a colon-list structure rather than a front-loaded purpose statement. It is concise but not well-structured as a tool definition.

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 and no annotations, the description is the primary source of information. It names the state sequence and refusal count, which is minimally useful, but it does not explain the return shape or whether it returns current state, full history, or aggregates.

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 baseline is 4. The description adds no parameter semantics because none exist, which is appropriate.

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 lists the application states and refusal count, implying it returns tracker status data, but it never states a clear verb or resource like 'Retrieves the application tracker.' It does not differentiate from siblings such as list_receipts 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no stated exclusions. The description merely lists data fields with no usage context.

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 only partially delivers: 'structures, never embellishes' is a genuinely useful behavioral guarantee about fidelity. However it says nothing about error handling, what happens with malformed input, whether one of the two inputs is preferred, or what the resulting profile contains.

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 core sentence is tight and front-loaded, but the parenthetical '(Facade addition: the concept's tool list omitted profile loading.)' is internal scaffolding noise that consumes attention without helping the agent act.

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 that produces a 'structured profile' with no output schema, the description should indicate what the profile contains or how it feeds downstream tools; it does not. It is adequate as a one-line statement of intent but leaves the agent under-informed about inputs and outputs.

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?

Both parameters (resume_path, resume_text) have 0% schema description coverage and the description never mentions either, nor whether they are mutually exclusive, nor which takes precedence when both are supplied with zero required params. The description does not compensate for the coverage gap 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?

States a specific verb and resource ('Parse a plain-text/markdown resume into a structured profile') and adds a scope qualifier ('verbatim — the parser structures, never embellishes'). No sibling tool covers resume parsing, so differentiation is not strictly needed, though the trailing parenthetical about a 'facade addition' muddies what the tool actually does.

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 statement of when to invoke this versus other flows (e.g., before search_jobs/match_jobs), no prerequisites, and crucially no guidance on choosing between resume_path and resume_text. The agent must guess the intake path.

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 it does deliver genuinely useful traits: entries are append-only and hash-chained, i.e. immutable and tamper-evident. It omits ordering, pagination behavior, default limit, what a receipt record contains, and whether all history 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?

A single front-loaded sentence fragment with no filler; the resource identity comes first and the enumeration follows. It is a fragment rather than a full clause, which slightly undercuts clarity but wastes nothing.

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

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

For a one-optional-parameter read tool with no output schema and no annotations, the description covers the ledger's nature but not result ordering, pagination, or receipt shape. Adequate to start, insufficient to call confidently without experimentation.

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 'limit' parameter is never mentioned in the description, leaving its default, maximum, and whether it truncates results undefined. With one undocumented parameter the description should have compensated, and it does not.

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 identifies the resource precisely as an 'append-only, hash-chained receipts ledger' and enumerates the event types recorded (grants, prepares, approvals, refusals, dry-runs, pause/resume), which is meaningful content beyond the tool name. It stops short of stating a verb or explicitly contrasting itself with the sibling action tools, so it 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?

There is no statement of when to call this versus alternatives such as get_tracker or search_jobs, and no prerequisites or exclusions. The event-type list implies an audit/verification use case, but the agent must infer it.

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, so the description carries the burden. It usefully discloses what the output contains (per-dimension rationale for title/skills/comp/location plus policy eligibility), but says nothing about whether scores are persisted, whether the call is expensive (it scores every cached job), or what happens when no policy/profile exists.

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?

One dense sentence with the action and scope front-loaded and no filler. The parenthetical dimension list is compact and informative rather than wasteful.

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 annotations and no output schema, the description does convey the scoring dimensions and eligibility outcome, which covers the essentials of the result. However, it omits prerequisites, mutation/persistence behavior, and cost, which matter for a tool that processes the entire job cache.

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 parameter 'limit' is never mentioned; 'every cached job' actively implies unbounded behavior, leaving the limit parameter's purpose and interaction with the scan scope unexplained. The description adds no parameter meaning 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 gives a specific verb ('Score') and resource ('every cached job') plus the comparison basis (profile+policy), so the operation is identifiable at a glance. It does not name a sibling, but 'cached job' scoring is naturally distinct from search_jobs and the application lifecycle 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?

There is no statement of when to call this versus search_jobs, or of prerequisites such as having a resume ingested and a policy set (both exist as sibling tools). The agent must infer that it should be run after ingest_resume/set_policy and before prepare_application.

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 behavioral burden. It adds real value by disclosing that the pause halts prepares and submissions and is 'receipted' (a side effect not otherwise documented), but it omits reversibility, permissions/authorization needs, and whether the pause is global versus scoped.

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 terse clauses, front-loaded with the highest-signal term ('KILL SWITCH'), and every sentence adds information (scope, effects, receipt). 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?

For a high-impact, irreversible-sounding mutation with no annotations and no output schema, the description conveys key semantics (immediacy, global scope, receipt side effect) but leaves significant gaps: how to undo, whether authorization is required, and what the undocumented reason parameter is for.

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 there is one optional parameter (reason) that the description never mentions. Since a parameter exists, the 0-param baseline of 4 does not apply, and the description does nothing to explain the purpose or expected content of 'reason'.

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 a specific action (pause) and states its scope ('everything') and effects ('prepares and submissions stop'), which distinguishes it from resumption/tracking siblings like resume and get_tracker. It stops short of explicitly naming resume as the inverse, but an agent can identify the operation 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?

The 'KILL SWITCH' framing implies an emergency/urgent context, so when-to-use is inferable. However, there is no explicit statement of when to use this versus resume, no prerequisites (e.g., authorization), and no guidance on when it is inappropriate.

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 load. It usefully discloses the failure path (recorded refusal with reasons) and a strong behavioral guarantee (verbatim facts, re-ordered only), which are real value-adds. It does not say whether a prepared application is persisted, whether repeated calls are idempotent, or what permissions/state must exist first.

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

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

A single dense sentence with zero filler: the policy gate is front-loaded, followed by the produced artifacts and the failure mode. Every clause 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?

For a one-param tool with no output schema, the description covers the important unknowns: what gets produced (tailored resume plus diff) and what happens on refusal (recorded refusal with reasons). Missing details are minor workflow prerequisites rather than call-blocking 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?

The single required parameter job_id has 0% schema description coverage and the description never mentions it, so an agent gets no confirmation that job_id is the target job (versus, say, an application or resume id). With one undocumented param, the description fails to compensate for the coverage gap.

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 and artifact: policy-check then build a PREPARED application, with the output contents named (tailored resume plus verifiable diff). That distinguishes it from approve_application or reject_application, but the description never names those siblings explicitly, so the boundary is inferable 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 phrase 'Policy-check, then build a PREPARED application' implies this is a pre-approval step, and the sibling set (approve_application, reject_application, set_policy) hints at the workflow. However, no explicit 'use this when...' or 'do not use this to approve/finalize' guidance is given, and prerequisites such as needing a policy set or resume ingested are 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?

With no annotations, the description carries the full burden. It does add real behavioral context: the actor must be the Owner (an authorization constraint) and the rejection is 'receipted' (a side effect that presumably feeds list_receipts). It omits whether rejection is reversible, what happens on an invalid state transition, and what the receipted result looks like.

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; the actor, action, precondition, and consequence are all packed in efficiently. Slightly terse, with jargon ('receipted') that could cost a sentence of clarity, 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?

For a two-parameter mutation with no annotations and no output schema, the description covers purpose, actor, precondition, and the receipting side effect. It is not complete enough to call safely, though, since the unexplained 'reason' parameter and the absence of any failure/reversibility guidance leave real 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 and it does not. The 'reason' parameter is never mentioned at all — an agent cannot tell whether it is required, free-text, or surfaced to the applicant — and application_id format/validity is also unaddressed.

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 (rejects) and resource (application) plus the required source state (prepared/approved), which distinguishes it from approve_application and prepare_application. It does not explicitly name the sibling it complements, but the state precondition does the differentiation work implicitly.

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

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

The phrase 'prepared/approved application' implies the calling context (after prepare/approve), so usage is implied rather than stated. There is no explicit 'use this instead of X' routing, no guidance on what to do if the application is in another state, and no mention of when rejection is inappropriate.

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 carries the full behavioral burden. It discloses owner-only authorization and a receipt side effect, but it does not explain what state changes, what happens if nothing is paused, reversibility, or what the receipt contains.

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 two terse sentences with the action front-loaded and no wasted text. The fragment 'Receipted.' is compact, though the extreme brevity contributes to the ambiguity elsewhere.

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 mutation with no annotations and no output schema, the description should clarify the target of the pause lift and what the receipt means. It leaves both unclear, so an agent still lacks key context needed to call it confidently.

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 parameter semantics are not a meaningful source of ambiguity. The schema is empty and fully specified by the input schema; the description adds nothing but needs to add nothing.

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 phrase 'lifts a pause' signals an un-pause operation, which helps distinguish it from sibling ingest_resume. However, it never names the resource or scope being resumed, so an agent must infer the target from siblings like pause.

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 guidance on when to call it, what preconditions must hold (such as an existing paused state), or which alternatives to consider. 'Owner' implies a permission constraint but does not provide workflow 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?

With no annotations, the description carries the full behavioral burden. It does disclose that the tool performs external network fetches against named public ATS feeds and writes a normalized cache, which is real added context. But it omits rate-limit/failure behavior, whether the cache is refreshed or merged, whether pagination exists, and what a call 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?

A single tight sentence with no filler, and the source list is useful rather than decorative. It is arguably too terse for the amount of undocumented behavior, and the capitalized 'REAL' is unexplained noise.

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 three-parameter tool with zero annotation coverage, no output schema, and 0% schema descriptions, the description is far too thin. An agent knows roughly which sites are hit but not what to pass, what comes back, or how caching affects repeated calls.

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 three parameters, so the description must compensate and largely does not. The provider list hints at what 'boards' contains, but 'query' and 'limit' are never mentioned, leaving the search semantics and result capping entirely 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 states a concrete verb and resource ('Pull REAL public JSON feeds ... and cache normalized jobs') and names the exact sources (Greenhouse/Lever/Ashby/Workable). However, it never reconciles the tool's name 'search_jobs' with the described fetch-and-cache behavior, so an agent cannot tell whether this searches or merely ingests job listings. The required 'boards' concept is only implied via the provider list.

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, no prerequisites, and no mention of any sibling despite 'match_jobs' plausibly covering a closely related job-related step. The agent must guess where this sits in the pipeline relative to match_jobs and the tracker 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?

With no annotations, the description carries the behavioral burden and usefully discloses that it returns the grant text and that nothing applies outside the granted scope. It still does not explain whether an existing policy is replaced or merged, how omitted optional parameters behave, or what authorization is required.

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 compact and front-loaded: purpose first, then the parameter scope, then return behavior, then the governing constraint. Every sentence contributes useful information with no padding.

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 nine-parameter policy mutation with no annotations and no output schema, it covers the essential shape: what is granted, which fields are involved, that grant text is returned, and that the scope is binding. It is still incomplete about optional-parameter defaults and whether setting a policy overwrites prior state.

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%, but the description names all nine parameters in human-readable form, from target roles through expiry. That prevents unknown parameters, yet it adds little semantic detail about defaults, units, or interactions such as how daily_cap and approval_threshold constrain applications.

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 action and resource: the owner grants application scope covering named fields. It is clearly the write counterpart to get_policy, though it does not explicitly name that sibling or spell out 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 is implied by 'The owner grants...' and 'Nothing applies outside it,' suggesting this tool is used to establish the governing scope. However, it gives no explicit when-to-use guidance, no prerequisites, and no named alternative such as get_policy for inspection.

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