HODDS

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

Beyond the annotations, the description discloses the auth requirement (organisation token via Authorization: Bearer hodds_...), the exact failure mode when it is missing (token_required), what the call returns (count acknowledged and count remaining for the organisation), and the replay behaviour. That is precisely the operational context the readOnly/destructive/idempotent hints cannot 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?

The verb and scope are front-loaded, then the effect, return values and auth requirement follow in priority order. It is dense but every clause carries information; the parenthetical nesting around 'all: true' is slightly heavy but does not waste 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 single-watch acknowledgement call with full schema coverage, an output schema and annotations, nothing an agent needs is missing: scope, exclusivity of the selection modes, idempotency, return counts and the token prerequisite are all covered.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning the schema does not state: alert_ids and all: true are presented as alternative selection modes for a single watch, which matters since neither is marked required in the schema. watch_id's role as the anchor for the operation is also made plain.

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 (acknowledges alerts) and scopes it to a single watch, spelling out both selection modes: explicit alert_ids or all: true. That is enough to separate it from siblings such as rate_alert, watch_need and unwatch_need without opening any 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?

It gives a strong usage cue: 'the only call that empties the pending delivery', which tells an agent this is the required action when pending alerts must be cleared. It also notes that replaying changes nothing. It stops short of naming an alternative sibling or an explicit when-not-to-use condition, so it falls just below 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 beyond the annotations: enumerates what is unaffected (listings, claims, declarations, ranking, the free coarse demand table), states the deferred effective date, names the required auth scheme (Bearer hodds_...), and predicts the exact failure mode (token_required). That is exactly the extra context annotations cannot carry.

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 effect and its timing, then scope-of-impact, then the auth prerequisite. The 'Contract 0.3.1' fragment is minor noise that doesn't help an agent decide or invoke.

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 needn't be explained. For a zero-param, destructive, idempotent cancellation the description covers effect, timing, side-effect boundaries, and auth failure — nothing an agent needs to call it safely is missing.

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

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

Zero parameters, so the baseline is 4; the schema has nothing to document. The description adds the non-schema prerequisite that an organization token must be supplied in the Authorization header, which is genuinely useful invocation context.

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 effect: 'Stops the subscription at the end of the paid period,' which tells an agent exactly what happens and when. The gap is sibling differentiation: `cancel_plan` exists and the description never says how this differs from it, nor does it use the word 'creator' anywhere in the body despite the title carrying 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?

The end-of-period timing implies when this is appropriate (deferred cancellation rather than immediate termination), which is useful context for selecting the tool. However, there is no explicit when-to-use/when-not guidance and no naming of `cancel_plan` as the alternative, leaving the sibling choice 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?

The description adds substantial behavior beyond the annotations: the cancellation is deferred to the end of the Stripe period, paid watches are closed but remain readable for 30 days, and the free watch plus agent tokens are unaffected. It also discloses the not_paid and token_required error paths and the bearer-token auth requirement, which is exactly the kind of operational context annotations cannot express.

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 with the core effect and timeline, then moves to side effects, preconditions, and auth. It is mostly efficient, though 'Contract 0.4.0' is a slightly unexplained detail that may not help an agent decide whether to call the tool.

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 a zero-parameter but destructive plan-cancellation tool with an output schema already available, the description is complete enough to call correctly. It covers the deferred timing, affected resources, preserved resources, auth requirement, business precondition, and two error outcomes.

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?

This tool has zero input parameters, so there are no parameter semantics to explain; the baseline for 0 params is 4. The description appropriately focuses on preconditions and side effects instead of inventing parameter details.

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: it 'stops the paid plan at the end of the Stripe period' and explains what happens to paid watches. It is clear on its own, but it does not distinguish itself from the sibling cancel_creator_plan, so an agent must infer which plan each tool applies to.

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 important precondition/branch: 'Without a paid plan the tool answers not_paid,' and it states the required organisation token. However, it never says when to choose cancel_plan instead of cancel_creator_plan or any other sibling, leaving the main routing decision implicit.

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 readOnly/idempotent annotations: it promises that unknown, stale, or conflicting data stays explicit, that an unknown price is never treated as zero, and that costs need full assumptions. It also discloses pagination strategy (repeat the call with `view` on large results) and a 409 restart condition, which annotations cannot express. Slightly reduced because 'one call per POST' is cryptic and the read-only claim sits oddly beside POST framing.

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

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

Front-loaded with what is compared, then behavior, then data-quality rules, then operational rules – dense and largely waste-free. A few telegraphic fragments ('Costs require all assumptions', 'one call per POST') trade clarity for brevity.

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-complexity 9-parameter comparator, the description covers paging, conflict recovery, missing-data policy, cost preconditions, and access scope, and an output schema exists so return values need no explanation. The remaining gap is parameter-level semantics for the priority/scenario machinery, which the description leaves entirely to an undocumented schema.

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

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

Schema description coverage is 0% across 9 parameters, so the description must carry the semantics and it only partially does: it constrains solution_ids to 2–3, implies requirements/criteria/context, ties cost_scenario to 'all assumptions', and points at `view` for large results. It says nothing about `priority`, `priority_required`, `locale`, the criteria-vs-requirements distinction, or the many required Scenario fields (users, currency, tax_basis, horizon_months, billing_periods, allow_current_price_projection).

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 verb and resource and quantifies scope ('Compare 2–3 catalogue IDs') plus the comparison axes (capabilities, offer, context, dated sources). It does not name or differentiate against siblings such as find_comparable_solutions or search_solutions, so an agent must infer that this is the deep multi-ID comparator rather than the discovery 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?

Indirect usage guidance is present: IDs must be discovered elsewhere (/api/capabilities, /api/solutions/{id}/specification), and cost comparison requires all scenario assumptions. However it never states when to choose this over find_comparable_solutions, search_solutions, or get_solution, and gives no exclusions.

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 mark the call read-only, idempotent, and non-destructive, but the description adds substantive behavior: it evaluates the whole pilot before applying limit, separates match/unresolved/mismatch, warns that coverage is catalogue not market, and explains pagination/409 handling. It also states public read access and that there are no billing/business writes.

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 purpose is front-loaded and the description is compact, with no filler. However, fragments like 'IDs/context: /api/capabilities' and 'one call per POST' are cryptic and slightly interrupt the flow.

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?

Because an output schema exists, the description need not explain return values, and it does cover key behavioral caveats and retry/pagination. Still, for a 9-parameter tool with nested predicate and scenario inputs, the missing parameter semantics leave an agent without enough guidance for advanced 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?

With 0% schema description coverage across 9 parameters, the description only glosses priority, reference_id, requirements, limit, and view; it does not explain criteria, cost_scenario, locale, context fields, or predicate operators/values. The complex nested Predicate/Scenario structures remain largely 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 first sentence states a specific verb/resource ('Find alternatives') and scope ('by required priority, optionally relative to one solution'). It distinguishes the task from plain retrieval, but it never names siblings like compare_solutions or search_solutions, so routing is not fully explicit.

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 implies the use case (finding alternatives for a priority) and gives operational handling for large results ('repeat arguments with view') and 409 retries, but it never says when to choose this over compare_solutions, search_solutions, or get_solution. No explicit exclusions are provided.

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 read-only, idempotent, and non-destructive behavior, while the description adds valuable context: it discloses the required organisation token, the token_required failure mode, pricing/billing handling, and that the plan does not affect ranking. It stops short of detailed operational notes such as rate limits, but the important behavioral traits are present.

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 front-loads the return contents and then adds billing, contract, and authentication context in a compact paragraph. It is dense but mostly purposeful, with only minor over-specific details such as the contract version.

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 rich annotations, the existing output schema, and zero parameters, the description provides what an agent needs: it explains the returned subscription data, the required organisation token, and the failure mode when the token is missing. Nothing essential is omitted.

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 there is no parameter-level semantics to document. The baseline for a zero-parameter tool is 4, and the description does not introduce confusion about inputs.

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

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

The description clearly states that the tool returns the organisation's demand-data subscription, including plan status, subscribed processes, pending removals, invoices, and payment provider. It is specific about the verb and resource, but it does not explicitly distinguish itself from siblings such as get_plan or cancel_creator_plan.

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 mentions the organisation-token requirement and the token_required error, but gives no guidance on when to use this tool versus alternatives like get_plan or cancel_creator_plan. The usage is implied by the name and return description rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it mandates an Authorization: Bearer hodds_... header and names the exact failure mode (token_required), and it explains billing semantics — one free watched solution, €0.50 each thereafter, €2 monthly minimum, billed if active at least one day of the period. It does not say whether past-due states block other operations, which would have pushed this to a 5.

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 return values are correctly front-loaded, but the middle is a dense run-on bundling pricing, VAT terms, invoicing, contract version and per-agent billing rules into one clause-heavy sentence. Much of the pricing detail is relevant context yet is delivered without structure, making the description harder to scan than its length warrants.

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 return shape is already covered, and the description still usefully names the plan states and auth requirement. Given zero params and full annotation coverage, an agent has everything needed to call it correctly; only the ambiguity against get_creator_plan leaves a gap.

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

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

The tool takes zero declared parameters, so the baseline is 4. The description still adds meaning by disclosing an out-of-schema requirement: the organisation token must be supplied as a bearer header or the call fails with token_required — information the empty input schema cannot convey.

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 — 'Returns the plan of the organisation of the token' — and enumerates the possible plan states (FREE, PAID, PAST_DUE, ENDING, ENDED) plus the billing artifacts returned. It is clear what the tool does, but it never disambiguates from the sibling get_creator_plan, which reads like a near-twin.

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

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

Usage is only implied: an agent infers you call this to read the current subscription state. There is no explicit when-to-use, no statement of when to prefer get_creator_plan or cancel_plan, and no note that this is the read path before a cancellation. The one concrete constraint given — an organisation token is required — is behavioral rather than selection guidance.

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

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, so the trailing 'Read-only' is redundant. The description earns credit elsewhere by disclosing data semantics an agent could otherwise misread: 'the first is primary' for processes, empty pricing models means unknown, non_attested means unconfirmed by the publisher, and unknown values are labelled as such.

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, front-loaded with verb, resource and id provenance before the field inventory. Every clause carries meaning, though the field list is long enough that the run-on structure makes it slightly harder to scan.

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?

Output schema exists, so return values need no explanation, yet the description still covers the interpretation traps (empty pricing, non_attested status, unknown markers, primary process ordering) that an output schema alone would not clarify. Nothing an agent needs to call or interpret this tool 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 schema already gives the example format, so the baseline would be 3. The description adds provenance semantics the schema lacks: the id is an option id originally returned by search_solutions, which tells the agent where a valid value comes from.

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 ('Returns one HODDS catalogue record by id') and immediately differentiates from the sibling that produces the id ('an option id returned by search_solutions'), so an agent can distinguish it from search_solutions, compare_solutions and find_comparable_solutions.

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 pointer that the id comes from search_solutions gives a clear usage context and implicitly sequences discovery before retrieval. There is no explicit 'do not use this when...' or naming of the comparison siblings, which keeps it 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds material context beyond them: the auth requirement (Bearer hodds_... token, token_required error), the read-side-effect-free guarantee, and the alert ordering/limit behavior. These are exactly the behavioral details an agent needs before calling.

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 a single front-loaded sentence that leads with the return shape before caveats, and every clause carries information. It is dense and slightly run-on, which costs a point against ideal structure, but there is 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?

Given an output schema exists, the description needn't detail return values, yet it still previews the payload contents, covers auth failure mode, and explains alert ordering. Nothing needed to invoke it correctly 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%, so the baseline is 3, but the description adds meaning by tying 'all: true' to the 200-alert cap versus the default 50 with unacknowledged first, clarifying the behavioral consequence of the flag. It also reinforces that watch_id comes from watch_need/list_watches.

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 ('Returns one watch of the organisation') and enumerates exactly what the payload includes: constraints, solution, challenger, switch brief, HODDS status, challenger_reason, and alerts. This clearly distinguishes it from list_watches (multiple) and ack_alerts (mutating).

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 sentence 'Reading does not acknowledge' implicitly routes agents to ack_alerts for acknowledgement, giving a clear use context. However, it never explicitly names ack_alerts as the alternative or states when-not to use this tool.

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 by disclosing the auth requirement (organisation token, 'Authorization: Bearer hodds_...') and the exact failure mode ('token_required' when absent). It also states the anonymity threshold governing what is aggregated and explicitly what is NOT returned (no need text, no organisation, no agent), which is meaningful behavioral context the annotations do not carry. It stops short of describing result volume or pagination.

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

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

Front-loaded with the verb and scope, then the payload list, then auth — a sensible ordering with no filler sentences. The 'Contract 0.3.1' string is the one element of dubious value for an invoking agent, and the parenthetical list is dense but each item carries information.

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

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

An output schema exists, so the field enumeration is redundant but harmless; the essential gaps an agent would have — auth requirement, failure mode, prerequisite of subscription, what is excluded from results — are all covered. It does not explain what 'subscribed' means operationally or whether results are bounded/paginated, which keeps it from a 5.

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 enum parameter is fully documented in the schema as a process id from /catalogue/processes.json. The description adds only the 'subscribed process' qualifier, which is a constraint rather than new meaning about the parameter itself, so the 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?

Opens with a concrete verb and resource ('Returns ... the gaps') scoped to a subscribed process, then enumerates the payload categories (watched needs, NO_MATCH, current choices, constraints, challengers delivered). This is clearly distinct from siblings like list_processes or list_watches, though the heavy internal jargon (HODDS, NO_MATCH, GAP_RESOLVED) is not defined for an outside agent.

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 'for a subscribed process' implies the precondition that the caller must already be subscribed, which is useful routing context. However, no sibling is named and there is no explicit when-to-use/when-not guidance versus list_watches, get_watch, or list_processes — the agent must infer that this is a read of derived demand data.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the trailing 'Read-only.' adds no information. The description does contribute the taxonomy's shape (two levels, bilingual labels, record counts), which sets expectations about result size and structure, but it says nothing about authorization needs or whether the catalogue is complete versus filtered.

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 payload information is front-loaded in the first sentence, and the search_solutions pointer follows logically. The closing 'Read-only.' is wasted text that only restates the annotations, but the rest is tight and free of filler.

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

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

For a zero-parameter read tool with a declared output schema, the description supplies what the schema cannot: what the taxonomy represents, example values, and how the returned ids feed into search_solutions. Nothing essential is missing, though a note on whether the list is exhaustive or environment-dependent would complete it.

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

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

The tool takes zero parameters, so the schema carries no semantic burden and the baseline is 4. The description goes slightly beyond by clarifying that the ids it returns are usable as the `process` argument elsewhere, connecting the output to a sibling's parameter.

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 (returns the HODDS process taxonomy) and names the exact contents: groups, processes, English/French labels, and per-process record counts. An agent can distinguish this from siblings like search_solutions or list_gaps without inspecting 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?

Explains the downstream use case directly: a process id returned here is accepted as the `process` filter of search_solutions, which tells the agent this is a discovery/lookup step in a two-tool workflow. It does not, however, name conditions for when not to call it or contrast it with other listing siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful operational context: an organisation bearer token is required and missing auth returns token_required, which is exactly the kind of behavioral detail annotations do not cover.

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, front-loaded with the action and scope, then the optional parameter and auth requirement. 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?

Given one optional parameter, full schema coverage, rich annotations, and an output schema, the description covers everything needed to call it correctly, including the auth prerequisite and failure mode.

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 sole parameter is fully documented in the schema. The description restates include_closed's effect but adds no format or edge-case detail beyond the schema, 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 ('Lists the watches of the organisation') and adds scope details (challenger, pending alerts, closed watches). The plural/list framing distinguishes it from the sibling get_watch for a single watch.

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?

Clear context for when to use it: to see organisation watches with challenger and pending-alert counts, optionally including recently closed watches. It does not explicitly name get_watch as the alternative for single-watch detail, so it falls short of full when/when-not guidance.

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

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

Annotations already declare non-destructive, idempotent, mutating behavior; the description adds valuable context beyond that: the ranking side effect is explicitly denied, the auth scheme (Bearer hodds_...) is stated, and the failure mode (token_required) is named. It does not explain what happens when an alert is re-rated, though the idempotent hint covers much of that.

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

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

Two tight sentences with no filler: the action and its allowed values come first, the behavioral constraint second, and the auth prerequisite last. Every sentence carries information an agent would not get from structured fields alone.

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 rich annotations, the description need not explain return values, and it covers the key extras: side-effect scope, auth, and the error surfaced on missing auth. Only the relationship to the similar ack_alerts tool is left unaddressed.

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 all four parameters, including the rating enum and the note's 500-character cap, are already documented. The description only restates the note length and rating values, adding no format or usage detail 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?

States a specific verb and resource ('Marks one alert relevant or not_relevant') and adds a scope qualifier ('never changes ranking'). It stops short of naming how it differs from the sibling ack_alerts, so an agent must infer that rating is distinct from acknowledging.

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 implies when the tool applies (rating an alert's relevance) and rules out a false expectation by saying it never changes ranking. However, it gives no explicit guidance on when to rate versus when to use ack_alerts or any other sibling, so the choice 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 declare readOnly/idempotent/non-open-world, and the description adds substantial extra context: the hybrid lexical+semantic ranking method, that sponsorship never affects ranking, that confidence is always UNKNOWN because records are non-attested publisher facts, and that results are never padded. This is exactly the kind of behavioral disclosure annotations cannot carry.

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

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

Front-loaded with the verb and resource in the first clause, and the later sentences on ranking, confidence and NO_MATCH all carry real information. It is a dense single paragraph, though, and the ranking-method detail (Cloudflare Workers AI embeddings) is more implementation trivia than agent-facing guidance.

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?

Even though an output schema exists, the description explains the response shape (request_id, status, options with id/label/description/provenance) and the meaning of the NO_MATCH state, which is what an agent actually needs to interpret results. Nothing material is missing for a 4-parameter, read-only search 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 coverage is 100%, so baseline is 3, but the description adds value: it gives concrete example needs and confirms the English/French language support that drives the `lang` parameter, and ties the catalogue's business-process organisation to the optional `process` filter. It stops short of elaborating the process enum values themselves, which the schema handles.

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 (searches) plus the exact resource (HODDS catalogue of software, SaaS, APIs and online services), the accepted input form (English or French need) and gives concrete example queries. An agent can distinguish this discovery tool from siblings like get_solution, compare_solutions or find_comparable_solutions without opening any 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 description implies this is the entry-point discovery tool and explains the terminal NO_MATCH status, but never explicitly says when to use it instead of compare_solutions, get_solution or list_processes. The only exclusions given are about results (no padding, no match) rather than about tool selection.

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 context beyond the annotations: it is the only write tool that needs no token, the report is an unverified caller statement, it never changes ranking by itself, and it fails with an error and stores nothing when storage is unavailable. The 'same report sent twice is stored once' line largely restates idempotentHint=true, which is the only redundancy.

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 that front-load the purpose and then layer auth, storage semantics and failure mode. The deduplication clause partly duplicates idempotentHint and the token contrast is slightly verbose, but there is little waste overall.

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 write tool with an output schema and full annotation coverage, the description supplies everything the agent still needs: prerequisites (a request_id/option_id from search_solutions), auth model, side effects on ranking, idempotency, and the failure behavior. 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%, so the baseline is 3, and the description earns one more by adding a constraint the schema cannot express: request_id and option_id must be passed 'exactly as returned' rather than reconstructed. The enum values themselves are already fully documented in the schema, so this is a modest lift over baseline.

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 ('Stores a declarative outcome report') plus the exact source of the inputs ('an option returned by search_solutions') and the accepted outcome values. An agent can distinguish it from every sibling, including the watch tools, without opening any 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?

Clearly establishes the triggering context (an option returned by search_solutions) and contrasts it with the watch tools that require an organisation token. It never explicitly says when not to call it or names a concrete alternative action for other cases, so it stops short of full routing guidance.

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

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

Beyond the annotations, it discloses key behavior: 402 responses, Stripe Checkout and Plan page destinations, that no charge occurs through this tool, immediate removals with continued readability until the paid period ends, empty-list refusal, and token-based authentication requirements. These are precisely the operational details an agent needs before invoking it.

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 with the core action and remains information-dense, but the billing/status sentence is somewhat convoluted. Most sentences earn their place, including the auth and empty-list caveats.

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 mutation semantics, billing implications, auth requirement, and output schema, the description is complete enough to call the tool correctly. It covers failure modes, side effects, and the alternative for empty selections.

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 exposes the allowed process IDs and required array, while the description adds key semantics not encoded in the schema: the call replaces the full list, an empty list is invalid, and cancellation should be used instead. It does not explain the enum values further, but the schema enum is self-contained.

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: it replaces the list of subscribed processes. It also distinguishes the operation from cancellation by saying an empty list is refused and should use cancel_creator_plan instead.

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 explicitly covers when this tool applies, what happens without an active subscription, what happens when adding with a subscription, and directs empty selections to cancel_creator_plan. The agent has clear routing guidance without needing to infer alternatives.

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, the description adds meaningful operational context: it requires an organisation token, returns the watch, recomputes the challenger later, and clears the solution when null is passed. It does not contradict the annotations and covers important auth/error behavior, though it could say more about side effects of changing the solution.

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 compact sentences with zero waste. It front-loads the core action and clearing behavior, then adds return/auth details efficiently.

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 annotations covering mutation/idempotency and an output schema covering return values, the description supplies the key additional context: auth requirements, token_required failure, null-clearing, and later challenger recomputation. It is nearly complete, though it lacks explicit sibling routing guidance.

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 watch_id, current_choice, and current_choice_name. The description adds useful semantics beyond the schema: it clarifies that the solution can be set by catalogue id or free name for any process, and that null clears the current choice.

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: it sets a solution on a watch by id or free name, and null clears it. The scope is clear enough to distinguish it from read-only siblings like get_solution, but it does not explicitly name or contrast an alternative for updating solution state.

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 implies usage by describing the action and null-clearing behavior, but provides no explicit when-to-use or when-not-to-use guidance. There is no mention of how this relates to alternatives such as get_solution, compare_solutions, or set_creator_processes.

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 context beyond the annotations: the erasure happens 30 days after closing (so data lingers, it isn't immediately purged), and an organisation bearer token is required or the call fails with token_required. This complements destructiveHint=true without contradicting it.

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

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

Two compact sentences, with the core action front-loaded and the retention/auth details following. No filler or 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?

With annotations covering the destructive/idempotent profile and an output schema handling return values, the description covers the remaining essentials: auth requirements and the 30-day lifecycle. Only the when-to-use routing is absent.

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 watch_id description already names the format (w_...) and where it comes from (watch_need or list_watches). The description adds nothing further about parameters, so the baseline of 3 applies.

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

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

"Closes a watch" states a specific verb and resource, and the title reinforces it. It is clearly distinct from siblings such as watch_need (creation) and get_watch (read), though it doesn't explicitly name them.

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

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

Usage is implied through terminology ('closes', 'watch_id'), but there's no explicit guidance on when to close versus when to keep or update a watch, nor any mention of alternatives like watch_need or cancel_plan for related cleanup.

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 annotations, the description discloses that the returned watch is initially 'not_computed', that alerts only arrive on following calls ('next_call' delivery), that unknown constraints stay uninterpreted, and that auth is required (token_required). Pricing and plan-gating (free_watch_used, plan_ending, 409 destination) are unusually thorough. It is consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=false.

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

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

The action statement is correctly front-loaded, but the body is a semicolon-chained run-on mixing billing, error codes, and auth into one dense block. Every fact is relevant, yet the packing hurts scanability — the pricing sentence in particular is a long clause sequence.

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 9-parameter mutation with a billing dimension, the description covers auth, return-state semantics, alert delivery, error-code routing, and pricing, and an output schema already handles return shapes. Little an agent needs to call this correctly 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 78%, so the baseline is 3, and the description adds genuine meaning: level semantics ('NEED default when need is given', CATEGORY needs a process and no need), process 'deduced from the need when absent', the single allowed delivery mode, and current_choice_name resolution behavior ('exact unique matches resolve, others stay unlinked').

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 opening sentence names a specific verb ('Opens a watch') and resource ('a need'), scoped to 'the organisation of the token', and clarifies the NEED vs CATEGORY mode. It does not explicitly name sibling tools like get_watch/list_watches/unwatch_need, so differentiation relies on inference, but the core action 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 implies usage via mode conditions ('CATEGORY follows a process', 'any process accepted', 'NEED (default when need is given)') and free-plan limits, but never states when to choose watch_need over search_solutions, set_current_choice, or unwatch_need. Error-code passages explain failure states rather than invocation guidance.

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