RepuTend

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

Annotations only declare readOnlyHint=true, so the description's addition that 'nothing is stored' is genuinely new and confirms the tool is a pure computation over inputs. It also discloses non-obvious behavior: the text carries no statement until one is recorded in the Defamation case, and the answer echoes inputs back in untrusted_business_facts. The prompt-injection warning about reviewer-authored fields is useful behavioral context. Remaining gap: no mention of error conditions, e.g. what happens for an ineligible or already-appealed case.

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 text is one dense block of run-on sentences that repeatedly switches between input fields, output fields, and eligibility rules without headings or ordering cues. It contains a literal duplication ('statement. statement.ask') and refers to output paths like business_facts.by before establishing what the response structure is. The first sentence is front-loaded, but the remainder is hard to parse and would cost an agent reading time.

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

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

With no output schema, the description must name the return content, and it does: appealability, recommendation, the untrusted_text to paste, statement guidance, attachment guidance, and echoed business facts. It also covers the Defamation-specific prerequisite that gates the text. It is short only on case_id and on failure modes, but an agent has enough to call this 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 description coverage is 0% and the object is nested, so the description carries the burden and largely meets it: it explains that business_facts.by is who at the business states the facts, .statement is what is stated, and .documents are file names for screenshots or PDFs. It even supplies a formatting rule ('start it in lower case') and a length-adjacent constraint ('screenshots or PDFs'). case_id is never explained, and statement.ask / attachments are output fields mixed in without markers, which keeps this from 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?

The opening clause names a concrete resource and outcome set: for a review Trustpilot kept online, it returns whether the decision can still be appealed, whether an appeal is recommended, and the paste-ready appeal text. That is a specific verb-plus-resource with distinguishable outputs, and the later instruction to pass business_facts to record_appeal implicitly separates this generation tool from the recording sibling. The awkward 'For a review Trustpilot kept online' framing and the scattering of output field names (statement.ask, statement.status, business_facts.by) blur the single-sentence purpose a bit.

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

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

There is real usage signal: 'once, within six months' bounds when an appeal is possible, and 'Pass the same business_facts to record_appeal' establishes the workflow order with a named sibling. However, there is no explicit statement of when to use this versus claim_packet, decline_packet, or regenerate_draft, and no when-not-to-use guidance. The guidance is implied through workflow coupling 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 only supply readOnlyHint=false, so the description carries the real burden and does so: it discloses the atomic per-draft scope, the draft_changed failure mode where nothing is approved, the human-in-the-loop requirement that the person must have read the draft, the mandatory accusation_untrue attestation for Defamation, and the capability gate (cases.approve_own). That is far more than the annotation provides.

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

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

Purpose and enabling condition are front-loaded, then failure handling, then the specialized Defamation rule in priority order. The dense parentheticals and long clauses make some sentences harder to parse than necessary, but every sentence conveys a distinct operational rule.

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

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

For a three-parameter mutation tool with no output schema, the description covers the precondition, the success condition, the failure token, and the conditional required nested parameter, which is nearly everything needed to call it correctly. The only omission is any statement about return values or post-approval state, which is acceptable absent an output schema but leaves a small 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?

With 0% schema description coverage, the description must compensate and largely does: draft_id is defined as 'the draft you showed the person (get_case's draft.draft_id)' and the nested accusation_untrue.attested_by is explained as naming the person at the company who attests the accusation is untrue. case_id is left implicit, which is a minor but real gap given no field-level schema docs.

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 ('Approve filing one of your cases') plus the enabling condition ('when your company requires approval (set_approval_required)'), which cleanly separates it from sibling tools like mark_filed and set_approval_required. 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?

Gives explicit when-to-use context (only when approval is required by the company setting), pins the approval to a single draft sourced from get_case, and prescribes the correct alternative path when draft_changed occurs ('show the person the newer draft and approve it only once they have read it'). It also carves out the Defamation precondition, so the agent knows a hard requirement before calling.

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 only readOnlyHint=false supplied, the description carries the real behavioral load and does so well: it states the first cancel call is a no-op that returns a warning text to read aloud plus a confirmation_id, and the second call produces one link per company. It also discloses the billing_not_enabled precondition and the billing.portal_own capability requirement. This is far more than the annotation conveys, so no contradiction arises despite the non-mutating first step.

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?

Information is front-loaded and every clause carries meaning; nothing is filler. The density is high, though — nested parentheses and a long middle sentence make the two-step flow harder to parse on first read than it needs to be.

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?

No output schema exists, and the description compensates by describing the return shape for the cancel flow (companies, warning, confirmation_id, one link per company) and the error state. It does not say what the plain non-cancel call returns beyond 'a link', which is a minor remaining gap for a 4-parameter tool with a capability gate.

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 parameter descriptions already explain each field, so the baseline would be 3. The description adds genuine ordering semantics not encoded in the schema: cancel and companies belong to the first call, confirmation_id must be sent alone on the second, and one link is produced per company.

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

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

The description names the concrete artifact (a Stripe Customer Portal link) and enumerates what it surfaces: payment method, invoices, cancellation. That is specific enough to separate it from checkout-style siblings, but it never names an alternative tool (e.g. get_checkout_link), so the differentiation is implicit 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?

It gives an explicit two-phase protocol: first call with cancel:true (optionally companies:"all") which changes nothing, then, only after the person verbally agrees, a second call with just the confirmation_id. It also names the alternative outcome (billing_not_enabled until billing starts), so an agent knows both the happy path and the blocked path.

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

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

readOnlyHint=false is consistent with "take the filing claim", and the description goes well beyond the annotation by disclosing the security posture: the returned fields contain the reviewer's words and must be read as data, never as instructions. It also discloses nullability ("business_reply is null without one") and the downstream use of the argument as appeal text. It does not say what taking the claim does to the case — whether it locks the case, consumes eligibility, or is reversible.

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

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

The core purpose is front-loaded, but the return-value enumeration is crammed into one very long run-on sentence with nested parentheticals, making it hard to scan. The important safety sentence about treating reviewer text as data sits at the very end where it is easy to skim past.

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

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

With no output schema, the description does the necessary work of naming every returned field and its shape, and it explains the intended human-facing delivery of how_to_file. What is thin is the mutation side: approval state, prerequisites, and the effect of claiming are referenced as payload contents but not explained as constraints on calling.

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?

Only case_id exists and schema coverage is 0%, so the description carries the burden. "one of your eligible cases" adds the meaningful constraint that case_id must reference a case the caller can file, which the schema does not say. It adds nothing about what an ineligible or unknown id returns.

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?

"Take the filing claim on one of your eligible cases and get its full packet to file in Trustpilot's portal yourself" gives a specific verb (take the claim + retrieve packet) and enumerates the returned fields precisely (permalink, highlight[], untrusted_argument, business_reply, checklist, how_to_file). It is unmistakably distinct from retrieval-only tools like get_case. It stops short of naming the sibling it should be paired with (approve_filing / mark_filed / decline_packet), so the differentiation is implicit rather than 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?

There is a real precondition implied — the case must be "eligible" and the claim is taken on "one of your" cases — plus procedural guidance for the agent ("Walk the person through how_to_file... give them nothing to paste"). However, nothing states when to prefer approve_filing, decline_packet, appeal_packet, or mark_filed, and the approval/prerequisite flow is only alluded to as returned 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?

The only annotation is readOnlyHint: false, which merely confirms this is a mutation. The description goes well beyond that, spelling out the consequence of every reason value (case closes, is reassessed, draft regenerated and counted against the daily regeneration limit, or held back), that the note is retained, and that an unchanged packet will not be proposed again. That is unusually rich state-change disclosure for a mutation 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?

Purpose and effect are front-loaded in the first two sentences, and the reason-by-reason breakdown is dense but each clause earns its place. The prose is a single long run-on block rather than a list, which makes the enum explanations 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?

For a three-parameter mutation with no output schema, the description covers preconditions, per-reason outcomes, side effects such as regeneration counting, and re-proposal behavior. An agent has everything it needs to call this correctly and predict the result.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does so for the enum: all six reason values are explained with their distinct downstream effects. The note parameter is only loosely covered ('note is kept for RepuTend', 'with a note saying why' for 'other'), and case_id is left implicit, so a small gap remains.

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 ('Say no to one of your cases before it is filed') and states the effect ('The case leaves the filing queue at once'), which distinguishes it clearly from sibling tools like approve_filing or appeal_packet.

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

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

It gives explicit preconditions and exclusions: 'Only a case waiting to be filed can be declined; a report already filed with Trustpilot cannot.' Each reason is framed as a selection criterion, which effectively tells the agent when to pick each one. It stops short of naming a sibling alternative (e.g. appeal_packet) for the already-filed case.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description does add genuinely useful semantics beyond that: the state enumeration, and the notable caveat that 'unknown' means the count could not be made and is never reported as zero, which prevents a serious misreading of the result.

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

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

One compact sentence that front-loads the state list and parenthesizes the important 'unknown' caveat. The trailing capability tag is noise for an agent, and the sentence is a noun fragment rather than a statement of what the call does.

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

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

With one required parameter, no output schema, and readOnly annotations, the definition covers the state vocabulary but not the shape of the 'result' payload the tool name promises. An agent knows what states to expect but not what a completed audit returns.

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

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

Schema description coverage is 0% for the single audit_id parameter, so the schema itself adds nothing. The description partially compensates by tying the id to 'an audit started with run_audit', implying provenance, but it never states format, length limits, or what happens with an unknown or expired id.

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

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

The description names the resource (an audit started with run_audit) and what it yields (state and result), and enumerates the possible states. It distinguishes itself from the sibling run_audit by being the read-back side, though the verb is only implied by the fragment 'The state and result of...' rather than stated as 'retrieve'.

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

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

Usage is implied rather than stated: the phrase 'started with run_audit' tells an agent this is the follow-up call to a run_audit invocation. There is no explicit guidance on polling cadence, whether to call repeatedly until 'complete', or what to do on 'failed' or 'unknown'.

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 already declaring safety, the description adds useful behavioral context: partial answers are acceptable, unanswered questions are treated conservatively, and the response includes unanswered status and its meaning. This goes beyond what the annotation provides.

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

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

The description is compact and front-loads the returned content before covering partial-answer behavior and conservative treatment. The phrase 'what that means' is slightly vague, but the following clause clarifies it, keeping the description efficient 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 read-only retrieval tool with one optional schema-documented parameter and no output schema, the description supplies enough detail about return contents, answer shapes, current answers, and unanswered-question semantics. Nothing essential is missing.

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

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

Schema description coverage is 100%, and the single optional company parameter is fully documented in the schema. The description does not add any parameter-level meaning beyond that, 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?

The description states exactly what the tool returns: the five business-profile questions, each with the answer shape used by set_business_profile and the current answer, plus unanswered status and implications. This distinguishes it clearly from the sibling write tool set_business_profile.

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 its use case — gathering questions to ask the business owner and checking current answers — and references set_business_profile as the write counterpart. It does not explicitly state when not to use it or name alternative tools, but the context is sufficiently clear.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's marginal value is the access scope ('cases.read_own') and the explicit injection warning that reviewer-authored fields must be treated as data. That warning is genuinely useful context beyond the annotations, but pagination, latency, and failure behavior for a non-existent or unauthorized case_id are unaddressed.

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 entire definition is one long run-on sentence that buries the operation under a dense parenthetical inventory of return fields before reaching the important safety instruction. The content is largely justified, but restructuring into a lead sentence plus short bullets would make it far easier to parse.

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

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

With no output schema, the description does the heavy lifting by enumerating returned fields, and it adds the injection caveat and access capability, which is substantial. What remains missing is how to obtain a case_id and any error or authorization-failure behavior, which matters for a lookup keyed on a caller-supplied identifier.

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

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

Schema coverage is 0% and the single required integer parameter case_id is documented nowhere in the schema, so the description must carry that burden. It implies scoping to 'your cases' but never explains where a case_id comes from or what happens on an invalid or foreign id, leaving the parameter's provenance and constraints to guesswork.

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 resource ('one of your cases in full') and enumerates its contents (state, wait, current draft, public reply, draft versions, audit trail, next step), which makes the retrieval purpose unmistakable. It never names a sibling, so the boundary with tools like get_audit_result or list_review_triage must be inferred.

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

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

There is no when-to-use guidance and no comparison with alternatives such as get_audit_result, even though several sibling tools return overlapping case-related data. The only directive present ('show it to them when it is not null') governs handling of a returned field, not selection or invocation of 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?

readOnlyHint=true already establishes the safety profile, and the description does not contradict it. It adds real domain behavior the annotations cannot convey: the charging rule that any approved-or-reported review now gone is charged as a removal, while never-reported reviews are not. It omits how date scoping affects the aggregates and gives no sense of response shape or size for what is clearly an aggregation payload.

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 sentence is front-loaded with the least controversial content (decisions, win rate, median days) before the removal/charging rules, which is good ordering. But it is a single run-on sentence with nested parentheticals, and the final two clauses about review charging are dense enough to require re-reading.

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

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

With no output schema, the description correctly shoulders the burden of explaining return values, and it does so thoroughly, including the per-reason breakdown. However, for a metrics tool the omission of any guidance on the `since` window — the one input that materially reshapes every returned number — leaves a real hole. Otherwise nothing an agent needs in order to call it 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 50%: `company` is documented in the schema (Trustpilot domain, only needed for multi-company keys), but `since` has no description at all, only a date-time format. The description mentions no parameters, so it does not compensate for that gap — an agent gets no explanation of what `since` filters (decisions date, report date, removal date) or whether it changes the win-rate denominator.

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

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

The description names a concrete resource set: Trustpilot decisions on filed cases, win rate, median days to decision, per-reason breakdown, and removal counts. That is far more specific than a tautology, and no sibling tool covers outcome metrics, so the resource is effectively differentiated even without naming an alternative. The verb is only implicit ('Your outcomes'), which keeps it 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?

There is no statement of when to call this versus e.g. get_case (single case detail) or get_audit_result, and no exclusions or prerequisites. Usage is only inferable from the content itself (reporting/metrics). The sole implicit constraint is the billing note about which reviews count as removals, which governs interpretation rather than 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?

Goes well beyond readOnlyHint=false by disclosing owner-only permission, the one-time-code email flow, member capabilities, team size cap, pending invite replacement that invalidates earlier codes, a 2-per-day email limit, and key replacement behavior for existing members.

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-loads the core purpose, then adds dense but useful behavioral constraints. Some sentences are awkward and parenthetical-heavy, but almost every sentence carries operational information rather than 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 mutation tool with no output schema and minimal annotations, it supplies the key context an agent needs: permissions, limits, replacement side effects, and edge cases for existing members and cross-team membership.

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 50%, and the company parameter already has a schema description. The description implies the email is the invitee address, but it does not explain the optional company parameter or the multi-company selection case, leaving a meaningful gap.

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

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

Starts with a specific verb and resource: inviting a colleague to the company's RepuTend account by email, with owner-only scope. It is clearly distinguishable from siblings such as remove_member, list_team, and redeem_invite.

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 owner-only use and operational constraints, including pending-invite replacement, team size limits, daily email limits, and existing-member behavior. It points to list_team for size, but does not explicitly route to redeem_invite or remove_member as 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?

Annotations only declare readOnlyHint=true; the description goes further by disclosing the response contents (role and account status) and the key-scoped access model, which is real behavioral context. It does not mention ordering, pagination, or what an empty result means, but for a zero-parameter read that is a minor omission.

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 compact sentences, front-loaded with what the tool returns before the cross-tool convention note. The middle sentence is slightly tangential to this tool's own invocation but earns its place as orientation for downstream calls. The trailing capability tag is boilerplate but harmless.

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, no output schema, and a read-only annotation, the description covers what the agent needs: what comes back and how the key scopes it. The only gap is the exact record shape (name, id, domain fields) and whether multiple companies change the result size.

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?

There are no input parameters, so the baseline is 4. The description adds orientation value by explaining the downstream convention — company plus Trustpilot domain when the key reaches multiple companies, versus case_id for case-scoped tools — which helps the agent use the output correctly.

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

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

The description names the resource and its contents precisely: the companies the caller's key reaches, plus role (owner or member) and account status. It is distinguishable from every sibling, which all operate on cases, reviews, or filings. It stops short of an explicit verb like 'list', relying on the tool name to carry that.

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 must infer 'call this to discover which companies your key can act on.' The second sentence is genuinely useful routing guidance, but it explains how other tools accept a company identifier rather than when to call this one. No exclusions or alternatives are 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?

readOnlyHint already covers safety, yet the description still adds real behavior: results are ordered newest first, closed cases are excluded by default, and the response may carry an Attack Mode suggestion with a price. It also clarifies that Attack Mode is never entered without the agent, which is meaningful for a read tool that surfaces a mutation path. Gaps remain on pagination behavior for limit/before_id.

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

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

Front-loaded with what the tool returns and avoids filler sentences, but the semicolon-chained phrasing is dense and the clause explaining 'next' and 'the words they can say to you for it' is wordy. Readable once, but harder to parse than necessary.

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

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

With no output schema, the description does list returned fields and the Attack Mode side-channel, which is the right burden to carry. It omits pagination semantics (default 100, max 200, before_id) and tier meaning, which an agent needs to page correctly or filter usefully.

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 only 20% (only 'company' is documented), so the description must compensate. It explains include_closed, but leaves the tier enum values (strong/arguable/candidate), limit, and the before_id cursor entirely undefined in both places, which is a substantial gap.

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

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

States a specific verb and resource: lists the company's reviews that RepuTend flagged as disputable or worth a look, and names the fields returned (state, tier, category, next). It is distinguishable from most siblings but doesn't clarify how it differs from list_review_triage, which sounds adjacent.

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

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

Gives conditional guidance for closed cases ('Closed cases only with include_closed') and instructs to surface the 'next' text to the user when non-null. It also routes Attack Mode actions to quote_attack_mode and set_attack_mode. However, there is no explicit statement of when to pick this versus list_review_triage or get_case.

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=true already declaring the safety profile, the description adds genuine context: what each record carries (label plus one-line reason), that RepuTend does not draft replies, and the scope required (cases.read_own). It omits pagination and default behavior, but that is a modest gap for a read-only listing 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?

Two sentences, front-loaded with what is returned, followed by the practical note about the 'respond' label. There is no padding, though cramming the capability tag and the reply caveat into the same flow makes it slightly denser than necessary.

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

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

For a read-only triage listing with no output schema and no required parameters, the description covers the returned fields and one workflow implication but leaves filtering and pagination semantics unaddressed. An agent can call it without a required param, but it cannot tell how 'before' pages or what limit does, which matters for the 'every review' framing.

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 only 25%: only 'company' is documented in the schema. The description merely restates the label enum values without explaining what disputable, genuine, or candidate actually mean, and it says nothing about 'limit' (default 50, max 200) or 'before' (a cursor), leaving two parameters carrying their full weight. It therefore fails to compensate for the coverage gap.

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

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

The description names a specific resource ('every screened review of your company') and the fields returned (label plus a one-line reason), which is far clearer than the bare name alone. It does not distinguish itself from the sibling list_disputable_reviews, even though the 'disputable' label overlaps that tool, so an agent could still hesitate between the two.

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

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

Usage is implied rather than stated: the mention of labels and the 'respond' recommendation suggests this is a triage overview, but there is no explicit 'use this when' clause and no exclusion pointing to list_disputable_reviews or get_case. The only actionable steer – that the 'respond' recommendation means reply publicly – is guidance for the workflow rather than for choosing the 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?

Annotations only declare readOnlyHint=true, so the description carries the rest: it discloses the required capability scope (team.read_own), which is a genuine authorization fact not present in structured fields, and clarifies that pending invites are surfaced alongside joined members. It does not cover return format or what happens when the key spans multiple companies, which keeps it off 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?

One compact sentence with the resource named first and the capability tag trailing in parentheses; nothing is redundant. The trade-off is a telegraphic noun-phrase style that reads as a contents list rather than a stated action.

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

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

For a low-complexity, zero-required-parameter read tool with a fully documented schema, the description is sufficient: it covers the roster contents, pending-invite nuance, the size limit, and the permission scope. The absence of an output schema is partly offset by the description effectively describing return values.

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?

There is a single parameter and schema description coverage is 100%, so the schema already fully explains the optional 'company' domain argument. The description adds nothing about that parameter, which is acceptable here but is the baseline rather than added value.

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

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

The description names the resource (the team) and enumerates exactly what is returned: owner, members, joined vs pending invites, and the size limit. That is specific enough to distinguish it from siblings like invite_member or remove_member, though it never states an explicit verb and does not name any sibling by way of contrast.

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 by the enumerated return contents: an agent can infer you call this to inspect team composition before inviting or removing a member. There is no explicit when-to-use statement, no prerequisite, and no pointer to alternatives such as list_companies or redeem_invite.

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 annotation only supplies readOnlyHint=false, so the description carries most of the burden and does add useful context: it is a live-claim-gated write, human verification is mandatory in manual mode, and a Defamation filing silently fails without the accusation_untrue attestation. It omits whether the call is idempotent, what happens on a rejected subreason, and what the response contains.

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

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

The core instruction is front-loaded, but the middle is three long run-on sentences stacking subreason and attestation rules, which makes it slow to parse. The trailing "(capability: cases.mark_filed_own)" is internal metadata that does not help the 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?

Given the complexity of the subreason branch and the Defamation attestation rule, the description covers the hard cases well, but there is no output schema and it never describes what a successful or failed call returns. It also references "manual mode" without indicating how the agent determines which mode applies.

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

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

Schema description coverage is 0%, so the description must explain the parameters and it largely does: verified_by is "who verified the packet", draft_id is "the exact draft_id", confirmed is "every checklist item marked confirm", and subreason/attested_by each get scenario-specific semantics. case_id is never explained and "in manual mode" refers to a mode that has no corresponding parameter, leaving a residual gap.

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

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

"Record that you filed one of your cases in Trustpilot's portal" states a specific verb (record a filing) and resource (a case in Trustpilot's portal), which is distinct from approve_filing and record_decision. It does not explicitly differentiate itself from those siblings, leaving the agent to infer the boundary between recording a filing and approving a packet.

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 concrete preconditions: a live claim packet is needed, and in manual mode a human check with verified_by, draft_id, and confirmed items. It also gives a hard stop condition ("without it nothing is recorded, so get it before you submit the report"). It never says when to call this instead of approve_filing or record_decision, so the alternative-routing guidance is absent.

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

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

Annotations already cover the safety profile (readOnlyHint=true), and the description adds genuine behavioral detail beyond that: the evidence integration is 'optional' and requires exactly one WordPress plugin for Easy Digital Downloads or WooCommerce, review screening is limited to 1–3★ reviews, and Attack Mode may be 'active, or suggested after a burst, with its price'. The '(capability: company.settings_own)' tag discloses the authorization requirement, which is useful even if slightly surprising for a read-only status call.

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?

All content is front-loaded in a single sentence, but that sentence is a long comma-delimited enumeration with nested parentheticals that is hard to scan. The information earns its place, but its density and lack of structure (no separation between what is returned and how it behaves) reduce readability.

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

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

For a read-only aggregate status tool with one optional parameter and no output schema, the description provides an adequate map of what the response covers, including edge behaviors like the 1–3★ review filter and conditional Attack Mode. A field-level return structure is absent, but the topical enumeration is sufficient for an agent to decide whether calling it answers its question.

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?

There is a single optional parameter with 100% schema description coverage, and the schema already explains the Trustpilot domain format and the multi-company condition. The description adds nothing about the company parameter, so the baseline of 3 is appropriate, though the impact is minimal given only one well-documented 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?

The description names the resource precisely ('Your onboarding checklist') and enumerates its constituent parts: account activation, team membership, billing state, Trustpilot delegated access, evidence integration, business profile, review coverage, and Attack Mode. This distinguishes it from per-topic siblings like list_team or get_business_profile_questions by making clear it is an aggregate view, though it never states the verb explicitly ('retrieve') or that it returns a consolidated status object.

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 framing 'Your onboarding checklist' implies the use case (checking overall setup progress), but there is no explicit when-to-use guidance and no sibling is named as an alternative or complement. An agent must infer that this is a one-call summary that supersedes calling list_team, get_business_profile_questions, and similar tools individually.

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

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

Annotations already declare readOnlyHint=true, so the non-mutating nature is covered by structured data. The description adds little beyond that: it does not say whether the call is cheap, whether it reports server version/status, or what a failure looks like. For a zero-parameter liveness probe the burden is small, but the description contributes almost no behavioral context of its own.

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

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

One short sentence front-loads the purpose with no wasted prose. The trailing '(capability: server.ping)' tag is internal metadata that adds nothing for an agent deciding whether to call it, but it is minor noise rather than a structural problem.

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?

There is no output schema, so the description is the only place a reader could learn what a successful ping returns (e.g., an ok flag or server version) or how failure is signalled, and it says nothing about either. For a trivial probe this is a modest gap, but it leaves the agent guessing about the response.

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 fully specifies the input surface and there is nothing for the description to disambiguate. Baseline 4 applies for a genuinely parameterless tool.

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: 'Check that the RepuTend MCP server is reachable.' That is unambiguous, and no sibling tool offers a health/connectivity check, so it is distinguishable by function even without naming an alternative.

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 use case (verify reachability) is implied clearly enough by the wording, but there is no explicit guidance on when to call it versus just invoking a real tool, nor any note about what to do on failure. A single clause such as 'use before a batch of calls' would have raised this.

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=false, the annotations only signal that this is not a read-only operation. The description adds substantial behavioral context beyond that: it discloses billing per activation, quoted price, quoted period, hourly review checks, priority screening, human confirmation, and an expiration constraint, though it does not cover failure handling or permission details beyond the capability note.

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 quote purpose and then flows into confirmation and expiration details. It is dense and somewhat run-on, but most of the information is relevant to pricing, activation, and the quote workflow.

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 quote-generation flow without an output schema, the description covers the key points an agent needs: what is being quoted, billing basis, confirmation requirement, quote_id dependency, and expiry. It could be more complete by clarifying what the tool returns or how it relates directly to set_attack_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?

There is only one input parameter, company, and the schema already documents it at 100% coverage. The description adds little beyond saying 'for your company' and noting the settings capability, so it does not meaningfully extend parameter semantics.

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 a specific action and resource: producing a quote for Attack Mode for the company. It explains the product terms (hourly checks, priority screening, quoted price, billed per activation), which makes the purpose concrete, though it does not explicitly distinguish this from the sibling set_attack_mode.

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

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

The description gives a clear usage flow: show the confirmation, wait for the person's yes, and use the quote_id before expires_at when entering. It does not explicitly name set_attack_mode as the alternative or state when quoting should be skipped, so it stops 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 only declare readOnlyHint=false, so the description carries the burden and does so well: it discloses the state transition to awaiting_tp, the eligibility rules that cause refusal, and the retention of business_facts until the reviewer is erased. The Defamation-specific meaning of those facts is extra context an agent could not infer 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?

The purpose is front-loaded in the first sentence and the remaining sentences each add a distinct constraint (state, refusals, retention). The inline qualifiers 'ref, optional,' and the trailing '(capability: cases.mark_filed_own)' are slightly awkward but cost little.

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 mutation tool with no output schema, the definition covers the state machine around the call, the refusal rules, and what happens to the supplied facts, which is what an agent needs to decide whether to invoke it. It does not say what a successful response looks like or whether any authorization beyond the stated capability is required.

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

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

Schema description coverage is 0%, so the description has to compensate, and it does for the two ambiguous fields: ref is constrained to Trustpilot's case/ticket number pattern and explicitly ruled out as a note, and business_facts is tied to what was passed to appeal_packet plus its retention and Defamation semantics. case_id and sent_at are left to the schema, which is a minor gap given how self-evident they are.

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: recording that an appeal was filed through Trustpilot's appeal form against a kept-online decision. It also distinguishes itself from the neighbouring record_decision step and from appeal_packet, so an agent can place it in the workflow 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?

It states the post-condition (the case returns to awaiting_tp until record_decision is called) and two explicit refusal conditions: a second appeal, and more than six months after the decision. What is missing is a positive instruction that appeal_packet must precede it; the link is only implied by 'as you passed them to appeal_packet'.

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 only readOnlyHint=false, the description carries most of the behavioral load and does note that a recorded decision cannot later be changed by the agent ('Only RepuTend can change a recorded decision') and that an appeal's outcome is recorded here as the next decision, which is valuable non-obvious context. It stops short of saying what state the case transitions to or what happens if the tool is called twice on a decided case (error vs overwrite).

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

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

The core action and the value mapping are front-loaded, and each sentence addresses a distinct failure mode (no decision yet, deleted review, ambiguous match, duplicate recording, appeal path). It is dense and somewhat parenthetical-heavy, so an agent must parse carefully, but nothing is filler.

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

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

For a two-parameter mutation with no output schema, this covers everything an agent needs: what to record, what not to record, how to disambiguate the case, the irreversibility of the write, and how later decisions arrive. The only omission is error/second-call behavior, which is minor here.

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

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

Schema coverage is 0%, so the description must compensate, and it does for `decision` by spelling out both enum values' real-world meaning. `case_id` is only indirectly explained (it must be one of 'your filed cases', discoverable via list_disputable_reviews/get_case) with no format or sourcing detail beyond that inference.

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

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

The description names a specific verb and resource ('Record Trustpilot's decision on one of your filed cases') and immediately maps the two enum values to the human-readable outcomes the agent sees in Trustpilot's UI (removed_by_tp = Removed, retained = Kept online). It is clearly separable from siblings like record_appeal, mark_filed and get_case, which are referenced only as downstream or lookup steps.

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

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

It gives explicit when-to-use rules and, more importantly, explicit when-NOT rules: 'Investigating is no decision yet, so record nothing' and 'A review gone from your profile is not a decision either.' It also prescribes a fallback procedure (match quoted review words via list_disputable_reviews then get_case) and an ambiguity rule (ask the user if more than one case could match), plus a once-only constraint.

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

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

Annotations only declare readOnlyHint=false, so the description carries the behavioral load and does it well: it explains that the call starts the reviewer's response window, computes a deadline, and that an unanswered window pushes the case to its report. The 'record once, and only after it was sent' note flags duplicate-write behavior, and the capability note signals the required permission. It does not describe error behavior for a case not in the waiting state, which keeps it off 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?

It is a single packed paragraph with the core action front-loaded, and every sentence carries information. However the phrasing is convoluted ('once it is over without an answer, the case goes on to its report, at once if it already is'), which slows parsing of an otherwise short description.

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?

There is no output schema, and the description fills that gap by stating the answer contains the recorded sent_at, the deadline, and a 'next' field. Combined with the lifecycle explanation, an agent has enough to call it correctly and interpret the response; only failure/precondition handling on the case state is left unstated.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for sent_at: omit for now, bare YYYY-MM-DD is treated as the end of that day in UTC, or a full date-time. case_id is only implied ('on one of your cases that waits for it') rather than defined, so one parameter's role remains slightly under-specified.

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 clause names a specific verb and resource: recording that a prerequisite information/update request was sent on a case awaiting it, with the two request types spelled out. It is clearly distinct from sibling tools like mark_filed or record_decision, though it never names an alternative explicitly and the phrasing is dense enough that an agent must read the whole paragraph to grasp the operation.

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

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

The description gives real when-to-use conditions: only on cases whose 'next step says which one and where to send it', and 'Record a request once, and only after it was sent', which also covers the do-not-call-early case. It lacks any direct routing against sibling tools (e.g. mark_filed), so an agent still has to infer the boundary rather than being told it.

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

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

Beyond readOnlyHint=false, the description discloses the operational essentials: the code is single-use and valid 7 days, a key-less redemption issues a new key shown once that replaces the prior key on every connection, and a key-present redemption joins the company to the existing key without disturbing other connections. It also spells out the mandatory post-redeem reconfiguration per client, which is exactly the kind of consequence an agent cannot infer from 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?

Purpose is front-loaded and the progression from redemption semantics to client-by-client reconfiguration is logical. However, the per-client minutiae (IDE 'Restart extension', quitting and reopening the desktop app, the note that ChatGPT chats never read the file) make it far longer than an agent needs to select and invoke 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?

For a one-parameter mutation with no output schema, the description is more than complete — it covers the single-use/expiry rule, key replacement blast radius, and the exact remediation path per client, leaving no correctness-relevant 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?

With 0% schema description coverage, the description must carry the meaning of 'code', and it does: the value comes from an invite email, is redeemable once, and expires after 7 days. It adds lifecycle semantics the schema's min/maxLength constraints cannot express, though it does not discuss format or validation.

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 names a specific verb (redeem), the exact resource (the code from a RepuTend invite email), and the outcome (join that company's team). An agent can distinguish this from the sibling invite_member, which is the issuing side rather than the redemption side.

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 clearly establishes the trigger context — an invite email code received by the person — and spells out the required follow-up for each client type. It stops short of explicitly naming an alternative or a when-not-to-use case, but the usage situation is unambiguous.

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 only readOnlyHint=false supplied, the description carries the burden and mostly succeeds: it discloses that the case leaves the filing queue, that prior approval is invalidated, that exhausted-attempt cases are restarted, that there is a per-company daily cap, and that it needs the cases.regenerate_draft_own capability. What it does not say is what happens to the existing draft text (replaced, archived, or versioned) or whether the operation is synchronous.

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

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

Four sentences, each carrying a distinct fact, with the core action front-loaded before the consequences and the rate limit. The parenthetical capability tag is compact and useful. Slight density in the second and third sentences, but no filler to cut.

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

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

For a one-parameter mutation with no output schema, the description covers the action, the side effects on queue and approval state, the retry semantics, and the rate limit, which is everything an agent needs to decide to call it and to expect the consequences. Return shape is not described, but no output schema exists and the case-oriented result is predictable from siblings like get_case.

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

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

Schema description coverage is 0% for the single case_id parameter, so the schema gives no more than an integer bound. The description only implies the parameter's meaning via "one of your cases' drafts", which conveys ownership scoping but not which case is eligible, what an invalid or ineligible case_id produces, or whether the id is the case or the draft.

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 and resource: have the drafter produce a new version of a draft belonging to one of your cases. No sibling tool in the list regenerates drafts, so there is no ambiguity to resolve, and an agent can tell immediately this is the regeneration path rather than the approval or filing path.

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

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

Usage is implied rather than stated: you call it when you want a fresh draft. The description gives no explicit when-to-use framing, no prerequisites to check before calling, and no named alternative (e.g., editing vs regenerating). The clue that it restarts a case whose drafting stopped is helpful context but is a behavioral note, not a selection guideline.

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

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

Annotations only declare readOnlyHint=false; the description adds real behavioral context beyond that — the effect is immediate ('Their key stops reaching your company at once') and it is restricted to owners. It leaves out whether the action is reversible, how to re-add a removed person, and what the call returns.

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

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

Two short sentences with the primary action first, the secondary case second, and the effect and permission constraint folded in without filler. The capability tag is compact metadata rather than noise.

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

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

For a two-parameter mutation with no output schema, the description covers what it does, who may call it, and the immediate consequence. Only the reversibility/aftermath and the result of the call are unaddressed, which are minor gaps at this complexity.

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 50%: the company parameter is fully documented in the schema, while email carries only format constraints. The description implies email identifies the person being removed or whose invite is cancelled, which adds a little meaning, but it adds no syntax, matching, or lookup guidance 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 uses a concrete verb+resource pair ('Take someone off your team') and adds the second case ('cancel an invite you sent'), which clearly separates it from invite_member and list_team. It stops just short of naming those siblings explicitly, so it is clear but not maximally differentiated.

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

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

It states the two situations that call for the tool (removing an existing member, cancelling a pending invite) and supplies the key prerequisite '(owner only)'. It does not name alternative tools or warn about cases where removal is the wrong action, so guidance is strong 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 only say readOnlyHint=false, so the description carries the burden and does real work: it discloses that the call creates a contact-claim record, that RepuTend ops review it manually before anything is provisioned, and that the response is deliberately non-enumerating. That is meaningful behavior an agent cannot get from structured fields. It omits idempotency on repeat calls, whether the caller must be authenticated, and any rate limiting.

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

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

Three short sentences, front-loaded with the action, then the side effect, then the response guarantee. Nothing is redundant or padded. The trailing '(capability: access.request)' is inert metadata but costs almost nothing.

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

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

For a two-parameter, no-output-schema mutation, the description covers the workflow and the response-safety property well. It does not say what the caller gets back (request id, status, confirmation email) or what to do next after submitting, which an agent needs to close the loop.

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

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

Schema description coverage is 0%, so the description must supply parameter meaning and only does half the job. 'Trustpilot business domain' implies tp_domain is a bare domain rather than a URL, but no format example is given, and contact_email is never mentioned at all despite being required.

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

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

The description gives a concrete verb and object: requesting RepuTend (access) for a Trustpilot business domain, and clarifies it records a contact claim rather than provisioning anything. That is specific enough to separate it from every sibling (all of which operate on cases, filings, packets, or teams). It stops short of a 5 only because 'RepuTend' itself is never defined for an agent that may not know the product.

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

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

Usage is implied rather than stated: an agent can infer this is the entry point when a business you want to work with is not yet set up. The note that the answer is identical whether or not the business already uses RepuTend is a useful routing hint, but there are no explicit exclusions or named alternatives (e.g. onboarding_status or claim_packet) for an agent deciding between them.

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 readOnlyHint=false annotation: it describes the job as asynchronous and bounded, defines the return envelope {audit_id, status, result?}, discloses caching behavior, and explains that for the caller's own company the count comes from the ledger and includes case ids. The mutation implied by readOnlyHint=false (creating a persistent audit job) is consistent with the returned audit_id.

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

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

Purpose and return shape are front-loaded and nothing is redundant, but several sentences are long multi-clause runs (the results-and-plans sentence in particular) that take effort to parse on a first read.

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

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

With no output schema and no annotation detail, the description still supplies everything needed to call and follow up correctly: input scope, async status handling, polling target, return envelope, UI-facing instructions for result.summary and result.next_step, and the cache/ledger exceptions.

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

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

The single 'domain' parameter has 0% schema description coverage, so the description must carry it and only partially does: 'any public Trustpilot business domain' implies a domain string rather than a full URL or a business id, but format, normalization, and accepted variants are never spelled out.

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 ('audit any public Trustpilot business domain') plus precise scope: reads the profile and low-star reviews, counts likely-disputable ones per category, and never returns review text. That last clause cleanly separates it from siblings like list_disputable_reviews and list_review_triage, which presumably surface text.

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 routing conditions: while status is running, poll get_audit_result; when result.next_step is non-null, direct the user to get_checkout_link for the chosen plan, or to request access while billing is off. It also flags that a repeat audit inside the cache window returns the cached result, so an agent knows not to expect a fresh run.

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

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

Annotations only supply readOnlyHint=false, so the description adds real value: it discloses that the tool works with or without an API key and that contact_email is only needed in the keyless case for a reply. It does not say what happens after submission (ticket id, storage, who sees it), leaving that 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 tight sentences, front-loaded with the purpose and followed by content restrictions and the key/contact_email caveat. The trailing '(capability: feedback.send)' tag is internal noise that adds nothing for an agent.

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?

Adequate for a five-parameter mutation with no output schema, but it omits what the caller gets back after submitting and does not describe two of the five parameters, so an agent must open the schema to fill in gaps.

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

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

Schema coverage is 0%, so the description must carry the load; it does well for contact_email (conditional on missing key and wanting a reply) and implies the kind categories, but 'tool' and 'client' are never explained and the enum values are only paraphrased loosely.

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 (tell/submit) and resource (feedback to RepuTend) and enumerates the exact situations covered: missing tool/feature, a tool that failed or answered wrong, or other problems. No sibling tool covers feedback, so an agent can immediately place it in the toolset.

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

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

Gives clear triggering conditions ('a tool or feature you needed and did not find', 'a tool that failed') plus explicit content exclusions (no review text, reviewer names, secrets). It stops short of naming an alternative for non-feedback needs, but no sibling competes here.

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

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

Annotations only supply readOnlyHint=false, so the description carries most of the burden and does it well: it discloses the downstream filing gate and the re-eligibility side effect of turning it off, plus the required capability (company.settings_own). It stops short of saying whether the setting is company-wide for all team members or confirming reversibility after filings are already queued.

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 front-loaded sentences carry the toggle semantics, and the trailing capability note is compact and useful. The phrasing 'no case of yours is filed until you approve its current draft' is slightly compressed but earns its 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 two-parameter state-changing setting with no output schema, the description covers purpose, both state semantics, and the linked approval tool. The remaining gap is verification/rollback guidance if the toggle lands in an unintended state.

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

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

With 50% schema coverage, the undocumented parameter is 'on', and the description does compensate by spelling out what On and Off mean operationally. The 'company' parameter is documented in the schema, but the description adds nothing about multi-company scoping beyond saying 'your company's'.

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

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

The description names a specific verb+resource pair: it turns the company's filing-approval policy on or off. It also defines both states and points at the directly coupled sibling approve_filing, so an agent can distinguish this settings toggle from the rest of the sibling list 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?

Usage context is explicit — enabling means nothing is filed until approve_filing is called on the current draft; disabling sends approval-only cases back through eligibility immediately. That tells the agent the consequences of each branch, but it never states prerequisites (e.g. required role) or when the agent should avoid flipping the policy.

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

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

Annotations only declare readOnlyHint=false, so the description carries real weight and does: idempotent retry behavior ('same idempotency_key returns the same activation'), no-op semantics and no charge when already on, and free deactivation. That is exactly the billing and retry context an agent needs before a mutating call.

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

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

Four short sentences, front-loaded with the action, then precondition, then edge-case behavior. No filler; the capability tag at the end is compact and useful.

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 four-parameter mutating tool with no output schema and thin annotations, this covers preconditions, idempotency, and charging edge cases well. It does not describe the shape of a successful first activation (fields returned, what 'current activation' contains), which would help the agent use the result.

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 only 25% (company only), so the description must compensate and largely does: quote_id is tied to the confirmed quote, idempotency_key is described as unique and retry-stable, and 'on' is explained via its on/off semantics. It leaves open whether quote_id is required specifically when turning on versus off, which the schema does not clarify either.

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 gives a specific verb and resource ('Turn Attack Mode on or off') with a boolean toggle, which is unambiguous. It does not name or contrast itself with the sibling quote_attack_mode, so an agent must infer the quote-to-activation flow rather than being told.

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 states the precondition for turning on ('only after the person said yes to the quote's confirmation'), which identifiers to pass ('that quote_id and a unique idempotency_key'), and that exit is free. Implicitly orders the agent against quote_attack_mode by requiring a prior quote confirmation.

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

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

Annotations only declare readOnlyHint=false, so the description carries real weight here: it discloses that each change creates a new profile version, that open cases are reassessed against it, that null clears an answer, and that the required capability is company.settings_own. What it does not say is whether the reassessment is synchronous or eventual, or whether prior versions can be restored.

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 compact sentences with the purpose front-loaded and the behavioral side effects after; there is little wasted wording. The phrase "keyed offering, service_area, ..." is slightly dense and would read better as an explicit list, which keeps it from a 5.

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 mutation tool with a deeply nested schema and no output schema, the description covers the mutation's side effects (versioning, case reassessment), the clearing convention, the capability requirement, and the shape of input. Nothing an agent needs in order to call it correctly is conspicuously 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 description coverage is 50% (only company has a description), and the description compensates by naming the five answer keys and explaining the null-clears-a-field convention, which the schema does not state explicitly. It stops short of explaining the semantics of the less obvious keys such as confused_with and expected_complaints, leaving the agent to infer them from key names and enums.

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 uses a specific verb plus resource ("Record answers to the business-profile questions") and immediately disambiguates the write path from the sibling read path by naming get_business_profile_questions. It also enumerates the accepted keys, so an agent can tell exactly what this tool does versus the question-fetching sibling.

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 parenthetical reference to get_business_profile_questions gives implicit sequencing (fetch questions, then record answers), and "Any subset" clarifies that partial updates are legal. There is no explicit exclusion or statement about when not to use it (e.g., versus onboarding_status or set_approval_required), so it stops 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 only declare readOnlyHint=false, so the description carries the behavioral burden and does add value: the secret is stored encrypted, and a signed health check sets the integration state afterward. This tells the agent the call is a mutation with a verification step. It omits what happens if the health check fails and whether a repeat call overwrites an existing endpoint.

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

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

Three short sentences, front-loaded with what to supply, then the effect, then the fallback. Nothing is wasted, though the trailing '(capability: evidence.manage_own)' is an internal tag that means little to an agent deciding how 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?

For a three-parameter mutation with no output schema and only a readOnlyHint=false annotation, the description covers the essentials: inputs, encryption of the stored secret, the post-write health check, and the no-plugin fallback. The open gaps are failure behavior and overwrite semantics rather than anything blocking a correct call.

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 33% — url and secret are bare strings with no schema descriptions, while company is fully documented in the schema. The description compensates partially by characterizing url as the plugin's HTTPS endpoint and secret as the plugin-generated secret that is stored encrypted. It adds no syntax or remark about the minimum length constraint on secret, so it only partially fills the gap.

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

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

The description names a specific verb and resource — connecting a WordPress evidence plugin by supplying its endpoint URL and generated secret. It is unambiguous about what is being configured, though it does not explicitly differentiate itself from any named sibling (there is no obvious alternative in the sibling list).

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

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

It explicitly marks the integration as optional and states the fallback condition: 'Without the plugin RepuTend runs on Trustpilot's public signals.' That tells the agent when this call is unnecessary, which is real usage guidance. It stops short of stating prerequisites (e.g. that the plugin must be installed first) or how to reconfigure an existing endpoint.

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