searchnapply

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world, so the safety profile is partly covered. The description adds genuinely non-redundant context: it excludes profile content and personal details unless the user asks, states the user's words travel verbatim, and describes the reply shape (receipt or failure sentence) plus a cost hint.

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 Purpose/When/Cost structure with the core action first and no filler sentences. Slightly dense long sentences, but every clause carries information (scope, privacy, verbatim text, response shape).

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 3-parameter tool with a nested `about` object, full schema coverage, annotations and an output schema, the description covers purpose, trigger, privacy behavior and the response contract. Little is missing; only repeated-call/idempotency expectations are left implicit.

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

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

Schema coverage is 100% and each field (kind enum, text length, about nesting) is already documented in the schema. The description reiterates rather than extends — 'with the posting or monitor it concerns when known' mirrors the schema's 'when known' phrasing — so baseline 3 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?

States a specific verb and resource ('Send the user's feedback on searchnapply to its team') and enumerates the cases it covers (wrong answer, fault, suggestion) with the optional subject. No sibling tool overlaps with feedback submission, so the agent can route it unambiguously.

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 'When' line gives an explicit trigger: a problem with searchnapply or its results arose and the user agreed to report it. No alternatives need to be named because no sibling does anything similar, but the guidance is context-only rather than a full when/when-not rule set.

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 (readOnly, idempotent, openWorld, non-destructive), it discloses a token cost (~1100 per posting), warns that descriptionText is untrusted third-party text rather than instructions, and defines what a not-found result means (stale posting). Those are exactly the traits an agent cannot infer from structured fields.

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 labeled lines — Purpose / When / Cost — with the most decision-relevant fact first and no filler. Every clause carries information an agent needs before calling.

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

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

With an output schema present, return-value explanation is unnecessary; the description supplies the remaining decision inputs (cost budget, untrusted-content handling, staleness semantics) for a 1-param read tool. Nothing material 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 coverage is 100% and the single param is fully documented, so the 3 baseline is already met; the description adds provenance ('from a search or a monitor') telling the agent where valid ids come from. The 'up to 10 at once' restates maxItems, hence not a 5.

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 ('Read') and resource ('chosen job postings in full') with a scope boundary ('up to 10 at once'), which cleanly separates it from job_postings_search: that tool finds postings, this one expands already-chosen ids.

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 'When:' line gives two concrete triggers — the user picks postings from a search or monitor, or asks for judging/tailoring. That effectively implies 'do not use for discovery', but no sibling is named by name and no explicit when-not is stated, so it falls short of a 5.

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

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

With readOnlyHint and openWorldHint already declared, the description adds useful behavioral context: default first twenty results and token cost per posting. It does not cover auth or rate limits, but it goes meaningfully beyond annotations and schema defaults.

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 front-loaded and cleanly structured into Purpose, When, and Cost. Every sentence provides useful information without repeating the schema or annotations unnecessarily.

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 17-parameter search tool with full schema coverage, output schema, and annotations, the description covers purpose, trigger conditions, defaults, token cost, and key filter semantics well. A minor gap is that it does not name the full-description or field-exploration siblings when explaining the short summary and field options.

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 schema already documents all 17 parameters in detail. The description adds only a little semantic nuance around salary and seniority filtering, leaving most parameter meaning to the schema as intended.

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: find job postings matching role, location, and fields, returning a short summary per posting. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as job_postings_search_fields or job_postings_get_full_description.

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: use when the user describes work they want, and gather a role and location first. It does not state when not to use it or name alternatives, but the triggering scenario is 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so safety is covered. The description adds behavior the annotations cannot convey: the no-argument mode returns the full field list, and it discloses token cost (~710 for fields, ~2370 for departments), which is genuinely useful for planning.

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 labeled lines (Purpose, When, Cost), front-loaded and free of filler. Every sentence carries information an agent needs.

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

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

An output schema exists, so return values need no explanation; purpose, trigger, default behavior, and cost are all covered. Only the explicit relationship to sibling search tools is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the meaningful default: with no arguments it lists every field and its values. Combined with the schema notes on `field`/`value`, an agent knows exactly what omitting parameters does.

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: explain every search field and its values, plus map departments to families and titles. This clearly separates it from the sibling job_postings_search, which performs searches rather than explaining fields.

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 'When' clause gives concrete triggers: before choosing a field the user did not spell out, or when a search result is ambiguous. It implies the relationship to search tools without naming them explicitly, so it falls just short of the when/when-not/alternatives bar.

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 declare that this is a non-read-only, non-destructive, idempotent, closed-world operation. The description adds useful behavioral context: it starts with already-matching postings, datePosted narrows that initial set, duplicate saves are refused, and the cost is about 160 tokens.

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, front-loaded with purpose, and organized into Purpose, When, and Cost. Every sentence adds useful information without repetition.

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 15 parameters, nested experience object, full schema descriptions, annotations, and an output schema, the description covers the essential creation behavior, required inputs, duplicate refusal, and cost. Minor gaps like permission requirements are not material for this closed-world 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%, so the schema already documents all parameters in detail. The description only restates that title and one location are required and that other fields narrow the search, so it does not significantly add meaning beyond the 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?

The description states a specific verb and resource: saving a search as a monitor that keeps collecting matching job postings. It clearly differentiates creation from monitor listing, retrieval, update, and deletion by focusing on persistence and collection.

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 'When' line explicitly restricts use to cases where the user asks to be kept informed about a search, which is a strong usage condition. However, it does not name alternative sibling tools such as job_postings_search for one-off searches or monitor_update for later changes.

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: it discloses the batch ceiling of 100 per call, that the response partitions succeeded from failed postings, the idempotent no-op case, and that postings the monitor does not hold are echoed back and left untouched. The cost note (~20 tokens per posting) is a rare and genuinely useful operational disclosure for an agent planning batch sizes.

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 labelled, front-loaded sentences (Purpose / When / Cost), each carrying distinct information with no repetition of the title or schema.

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

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

An output schema exists and the description still usefully signals that it splits decided from failed results; combined with the batch, idempotency and cost notes, an agent has everything needed to size and interpret a call correctly.

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

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

Schema coverage is 100%, so the enum meanings, the 1-100 bound and the monitorId source are already documented in structured fields. The description's 'up to 100 postings at once' and 'put postings back' restate the maxItems and the 'open' enum value rather than adding new semantics, 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 and resource ('Record what the user did with postings a monitor found, or put postings back') and scopes it to monitor postings, which cleanly separates it from monitor_create/update/list/get and the job_postings_* siblings. 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 explicit 'When: After the user says what they did with a posting, or wants a decided posting back' gives a concrete trigger condition. It does not name an alternative tool or an exclusion case, so it stops short of a 5.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses irreversibility, cascade scope ('everything they collected'), and partial-failure semantics: an unknown or already-deleted id is returned in the result and does not block the remaining deletions. That is precisely the behavior an agent needs before calling a destructive batch tool.

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 labeled lines (Purpose, When, Cost) with the destructive scope front-loaded and zero filler. The cost line is unusual but earns its place by telling the agent the reply is cheap to inspect.

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

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

With an output schema present and annotations covering the safety profile, the description covers the key gaps: irreversibility, batch failure handling, and a token budget. 'Everything they collected' stays somewhat abstract about what dependent data is removed, which keeps it just short of 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?

Schema coverage is 100% and the schema already documents the 1-10 array with its bounds; the description adds no format or selection detail. The schema's own pointer to monitor_list supplies the provenance. 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 states a specific verb and resource ('Delete saved monitors') and adds scope ('and everything they collected'), which tells an agent this is a cascading delete rather than a status change. It is clearly distinguishable from siblings like monitor_update or monitor_decide.

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 ('Only when the user asks to delete them'), which excludes proactive or inferred deletion. It does not name an alternative for reversible actions (e.g., monitor_update to disable), so the when-not guidance is partial rather than complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description earns credit for adding information the annotations cannot: a concrete token cost (~3440 tokens per 20 postings) and the pagination unit of 20. The note that 'a posting can be old while still hiring' is useful but phrased in a way that is easy to misread.

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?

Labeled Purpose/When/Cost sections front-load the key information, and each line adds something (scope, trigger, cost). The first sentence is long and chains several clauses together, which slightly hurts readability, but nothing is truly redundant.

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

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

An output schema exists and annotations cover the safety profile, so the description only needs the operational details: pagination, default filtering, and cost, all of which are present. A mention of how monitorId relates to monitor_list would complete the picture, but the schema notes that already.

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 schema already documents all three parameters at 100% coverage, so the baseline is 3. The description goes further by restating that page is 1-based with 20 postings per page and by spelling out what an unset state means in user terms (postings not yet decided on) versus the handled/set-aside alternatives, which links the enum values to intent.

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 opens with a specific verb and resource: it shows a single monitor plus its counts and a page of its collected postings, which distinguishes it from the sibling monitor_list. It stops short of naming any sibling explicitly, so the differentiation is implied by 'one monitor' 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 'When' line gives clear trigger conditions (user asks what a monitor found, or wants to see already-decided postings), and the default-state rule tells the agent the common case. It does not name alternatives such as monitor_list or job_postings_search for cases where the user wants raw postings instead.

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?

Adds real value beyond the annotations (which already declare readOnly/idempotent/non-destructive): completeness (no monitors omitted), per-monitor cost (~140 tokens), and the semantics of the count categories. The ordering claim ('the order they come back') is left vague rather than named (creation date, name, etc.), the one real 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 labeled lines (Purpose/When/Cost) front-load scope, then selection guidance, then a budget. Every sentence carries information an agent needs; nothing repeats the schema or annotations.

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

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

With an output schema present, return values needn't be documented, yet the description still explains the count buckets and the cost — enough to call this confidently with no arguments. Only the unspecified sort order keeps 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 tool takes zero parameters, which is the baseline-4 case. The description correctly implies no inputs are needed and instead spends its words on the return shape.

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 ('List every one of the user's saved monitors') plus a scope guarantee ('none are left out') and what each row contains (counts). This implicitly separates it from monitor_get (single monitor), though no sibling is named outright, keeping it just short of a 5.

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

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

'When: Before choosing or changing a saved monitor, to find the one the user means' gives a clear triggering condition and implies the follow-on tools (monitor_get, monitor_update, monitor_decide). No explicit when-not or negative case is stated, so it falls short of a 5.

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

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

Goes well past the annotations: discloses partial-update semantics (only sent fields change), the failure mode for a result that would duplicate another saved monitor (a plain sentence instead of the monitor), the success return shape, and a token cost estimate. Annotations already cover safety/idempotency flags, and the description adds the missing behavioral context about what is preserved versus overwritten.

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 labeled sentences (Purpose/When/Cost), front-loaded with the operation's contract and free of repetition. Every sentence carries distinct information an agent needs before calling.

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 16 parameters, an output schema, and full annotation coverage, the description covers the essentials: partial update, refusal case, return value, and cost. It is slightly thin on failure modes like an unknown monitorId and does not address the destructiveHint=true flag explicitly, but the output schema and annotations offset most of that.

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 the baseline is 3, but the description adds real meaning for a 16-parameter tool by framing all non-required fields as optional patches that leave current values untouched. It does not detail defaults or enum semantics beyond what the schema already states.

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 (change a saved monitor) and immediately pins down patch semantics: 'send only what changes, since everything else stays as saved.' That distinguishes it from monitor_create or a full replace, though it never names a sibling tool the way an ideal definition would.

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 'When:' clause gives a concrete trigger (user wants a different title, location, company, keyword or field on a saved monitor), which is better than implied usage. But there is no when-not guidance, no prerequisites, and no routing to siblings such as monitor_create, monitor_get, or monitor_delete for adjacent intents.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: empty sections signal unfilled data, and a cost estimate of ~1410 tokens for a filled profile lets the agent budget 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?

Three labeled lines (Purpose/When/Cost) with zero filler, and the core purpose is front-loaded ahead of the usage condition and cost note. 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?

With an output schema present, the description need not explain return values, yet it still flags the one interpretive detail an agent needs (empty section = not filled in). Cost disclosure plus usage trigger makes this complete for a zero-param read 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax or filtering behavior the description could usefully add. The description's note about per-section emptiness is output semantics rather than parameter meaning.

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 ('Read') and resource ('the user's profile') along with the shape of the content ('section by section, with the rules for a tailored resume or cover letter'). This clearly separates it from the write-side sibling profile_update without needing to open either 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 'When:' line gives two concrete triggers: before tailoring a resume/cover letter, or when the user asks what their profile holds. That is clear usage context, but it names no exclusions or alternatives (e.g., 'use profile_update to change it'), so it stops short of the explicit when/when-not pairing.

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 destructiveHint=true, but the description explains precisely what is destroyed and how: omitted entries in a sent section are dropped, so every retained entry must be re-sent with its id. It also discloses the validation rule (unknown section names refused) and a response token cost, all beyond the annotations.

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 labeled fragments (Purpose/When/Cost) front-load the replacement rule first, then usage, then cost. Every clause carries non-redundant operational information; nothing is 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 destructive, nested-object mutation the description covers replacement semantics, id requirements, validation limits and cost. With an output schema present it correctly does not waste words describing the returned profile 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 coverage is 100%, so baseline would be 3, but the description adds decisive semantics the schema does not state: whole-section replacement, id reuse from a prior read, and the ten-section limit. These change how an agent constructs the payload, not merely what it names.

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 target ('Replace whole sections of the user's profile') and immediately clarifies the replacement semantics — a sent section overwrites the stored one in full. That distinguishes it from any partial-patch sibling and from profile_get without needing to open a 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?

Explicit activation condition ('the user asks to add, fix or remove something in their profile') with an exclusion ('not on the assistant's own initiative'). It stops short of naming profile_get as the mandatory read-it-first companion, only alluding to 'the ids read earlier'.

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 and non-destructive, so safety is covered. The description adds genuine context beyond them: prices are intentionally omitted, unknown values are dropped rather than fabricated, and the call costs roughly 50 tokens. That last point in particular is not derivable from any structured field.

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?

Labelled Purpose/When/Cost lines make the entry points scannable and front-load the verb. Every sentence carries information, though the 'prices are on the pricing page' clause is slightly redundant with the 'Cost' label's different sense of the word 'cost', which may momentarily confuse.

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

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

An output schema exists, so return values need no explanation, and the description covers scope, exclusions and invocation cost. For a zero-parameter, annotated, read-only tool this is close to fully sufficient; only an explicit note on sibling relationship (e.g. when to prefer subscription_links) 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly spends no words on parameters and instead uses the space for scope and cost.

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 Purpose line names a specific verb and resource ('Read the user's searchnapply subscription') and enumerates what is returned: daily call limit and today's usage. It also carves out what is not returned (price), which sharpens the boundary. It does not name the sibling subscription_links, so it stops short of a 5.

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

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

The 'When' clause gives three concrete user-intent triggers (cost, trial end, tool stopped answering), which is strong routing guidance. It redirects pricing questions to the pricing page rather than to a sibling tool, and it never explicitly excludes a sibling or names an alternative call, so it is clear but not exhaustive.

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 real value: it discloses that replies are link-only, that no price is embedded, and that mutations must happen on the site. The 'Under 30 tokens' cost note is a useful behavioral signal not present in structured fields.

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?

Labeled Purpose/When/Cost sections make it front-loaded and scannable at roughly 45 words. Minor slack from the slightly overlapping 'no price is stated here' clause, which restates the pricing-link point rather than adding new 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 parameters, rich annotations, and an output schema that covers the return shape, the description supplies everything an agent needs: what comes back (two links), when to call it, and that it costs almost nothing. Nothing material 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 takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond what the empty schema already conveys.

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 resource (the two subscription site pages: pricing and the billing-portal account page) and clarifies scope by noting 'no price is stated here,' which functionally separates it from subscription_get. It falls short of a 5 only because it never names subscription_get as the sibling the agent should prefer for plan/price data.

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: The user wants to see prices, subscribe, change or cancel' gives explicit triggering intent, and 'changes happen on the site, not in this assistant' pre-empts misuse for actual mutations. There is clear routing context but no named alternative tool for the price-lookup case.

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