SignalPipe

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

Annotations only declare this is a non-idempotent write. The description goes far beyond that, explaining the scoring pipeline (embedding floor, vertical gate, 3-judge swarm), that buy_signal_keywords is an AND-gate that silently zeroes non-matching posts before logging, and that competitor mentions floor the score. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose and workflow, then organized per-parameter with concrete examples. It is long (~350 words), but nearly every sentence carries non-obvious guidance, so the length is largely earned rather than padded.

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 7-parameter mutation tool with no output schema and no enums, the description supplies the absent decision rules: how to source anchors, how to phrase them, how keywords gate scoring, and how to scope audience/value_prop. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds substantial meaning: anchor_sentences constraints (3+, 5-40 words) with buyer-vs-seller GOOD/BAD examples, the narrowness requirement on target_audience/value_prop because judges read them, and the risk rationale for leaving buy_signal_keywords empty.

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 line names a specific verb and resource with scope: 'Register a new product to monitor for buying signals.' Combined with 'Then `reload_products` to activate,' an agent can distinguish this from update_product and get_products without opening a schema.

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

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

Gives an explicit required workflow: call `suggest_anchors` FIRST, get user approval, then `reload_products` to activate. It also names the conditions under which optional fields should be left empty or split into separate products, which is the when/when-not guidance the dimension asks for.

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 declare a non-read-only, non-idempotent, non-destructive write, and the description adds behavior beyond them: every feed costs a fetch per cycle and sources rate-limit, and twitter_search behaves differently than its name suggests. It does not address duplicate/re-add behavior or error outcomes, which is a minor gap given idempotentHint=false.

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

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

Front-loaded and scannable, but ~230 words with repeated editorializing: 'Add 3-5' is restated as '3-5 well-chosen feeds beat 20,' and 'prefer broad communities' overlaps with 'go where your buyer complains.' The CHOOSING STATIONS block is longer than the operational payload requires.

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 100% schema coverage, the description carries the platform and strategy burden well, including which platforms need a feed URL and which do not. It stops short of stating what a successful add returns or how duplicates are handled, but nothing essential to making the call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning on top: concrete URL patterns for Reddit and HN, the requirement to use /new/.rss rather than /.rss, and the clarification that twitter_search needs no rss_url and does not read X. It slightly duplicates schema text but the platform/URL semantics are genuinely extra.

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

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

Opens with a precise verb+resource: 'Add a feed for a product to monitor,' immediately followed by scope guidance ('Add 3-5'). An agent can distinguish this from list_stations, remove_station, update_station and preview_station purely from the description.

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

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

Explicit when-and-how guidance: add 3-5 stations, valid platform values enumerated, and a hard exclusion — twitter_search 'only routes outreach to X; it does NOT monitor X.' It also gives selection criteria (broad communities over narrow keyword searches) and tells the agent to ask the user for sources.

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 tell the agent this is a non-read-only, idempotent, non-destructive call; the description goes further by disclosing a side effect that annotations cannot express — approval also rewards the source feed and records the mission as a positive `replied` outcome. It even notes this behavior will change when the sidecar is wired, which is useful forward-looking context. It stops short of describing permissions or the response, but the hidden feedback-loop effect is exactly the kind of trait that matters here.

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 is front-loaded well, but the middle sentence spends considerable length on the RL-loop/sidecar roadmap, which is background rather than actionable instruction. It is organized but not tight — the roadmap detail could be compressed.

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 description supplies the key missing pieces: the operator-signal semantics, the dual-meaning caveat, and the feedback side effect. An agent can call this correctly without opening anything else, though it lacks any return-value or error context.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's note that omitting `edited_draft` keeps the existing draft largely restates the schema default. Baseline 3 is appropriate since the schema does the heavy lifting.

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 gives a specific verb and resource (approve a mission) plus the immediate consequence (queue it for outreach), so an agent knows the action and effect. It implies a counterpart to reject_mission/delete_mission but never names a sibling, so differentiation is left to the tool name.

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 explains the meaning of approval and how that meaning shifts between the manual outreach phase and the future autonomous sidecar, which is real usage context. However, it never states when to prefer this over reject_mission or draft_mission, so routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond that by disclosing the critical non-obvious side effect: the source station's rl_weight is left untouched and no learning occurs, contrasted against reject_mission's penalisation. This is exactly the kind of behavioral context annotations cannot carry.

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

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

The one-line summary and the delete-vs-reject contrast are front-loaded and every section earns its place, but the prose is longer than a single-parameter tool strictly needs and repeats the 'no learning / rl_weight untouched' point across paragraphs.

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, full schema coverage, no output schema, and annotations covering the safety profile, the description supplies everything an agent needs: what is destroyed, that no learning side effect occurs, and how to choose it over reject_mission.

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 mission_id parameter is already documented as coming from get_missions. The description adds no format, syntax, or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('hard-delete a mission') plus the key scope qualifier ('silent cleanup only'). It explicitly differentiates from the sibling reject_mission, so an agent can route without opening either schema.

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

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

Provides explicit when-to-use (post deleted, duplicates, accidental scrapes), when-not (anything where you can categorise WHY), the named alternative (reject_mission), and a default tie-breaker preferring reject_mission. Textbook routing guidance.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=false and destructiveHint=false, so the mutation/idempotency profile is already covered. The description adds real value beyond that by disclosing the payload's nature ('working payload, not a display payload') and an explicit behavioral constraint ('do NOT dump the full payload back to the user'), though it does not state auth or rate-limit behavior.

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

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

Purpose and the key 'working not display' warning are front-loaded, followed by a compact numbered workflow. Every sentence earns its place and there is no padding or redundancy.

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, yet the description enumerates the payload contents (product positioning, lead text, scoring breakdown, response schema) the agent must use, and supplies the full drafting lifecycle. Nothing essential for correct invocation is missing.

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

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

With a single parameter at 100% schema coverage, the schema already documents mission_id (including its provenance from get_missions). The description adds minor value by confirming the call signature ('Call this with the mission_id') and tying it into the workflow, so it supplements rather than repeats the schema.

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

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

States a specific verb and resource ('Get the drafting payload for a single mission') and immediately clarifies its downstream purpose ('so you can write the reply'). It also distinguishes itself from display-oriented data and from sibling tools by name, so an agent can tell what this does versus upload_draft or get_missions.

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?

Provides an explicit numbered workflow covering when to call it, what to do next (upload_draft), and the concrete alternative (reject_mission when the lead is not a buying signal). The when-to-use and when-to-skip conditions are both spelled out.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description goes further by disclosing the payload's contents (system prompt, history, persona voice, response schema) and the constraint that the cap is enforced downstream in record_message. It doesn't state payload size or token limits, which is the only remaining gap.

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

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

Front-loads the core purpose in the first sentence, then layers the working-vs-display distinction and a compact three-step workflow. Every sentence carries actionable information with no 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?

With no output schema, the description compensates by enumerating what the payload contains and tying it to the downstream record_message call. An agent has everything needed to fetch, use, and then persist the drafted message.

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

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

Schema coverage is 100% and the single parameter already documents that prospect_id comes from get_pipeline, so the schema does the work. The description names prospect_id in the workflow but adds no format or syntax beyond what's structured.

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 ('Get the drafting payload for the next outreach message') and immediately distinguishes itself as a working payload rather than a display payload. An agent can separate this from siblings like get_pipeline and record_message without opening either schema.

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

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

Gives an explicit numbered workflow (call with prospect_id, compose, then call record_message with its signature) and an explicit exclusion ('do NOT dump the prompt or conversation history back to the user'). The daily send cap and where the cap-hit error surfaces are also spelled out.

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

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

Annotations already declare readOnly=true, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that: it enumerates the per-mission payload (id, score, channel, snippet, handle, role, draft) and explicitly warns against shell/file inspection because data is already structured. Pagination or result-size limits are not mentioned.

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

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

Front-loaded with the purpose, then a compact field list, then presentation rules. Every block earns its place, though the presentation paragraph is slightly wordy with its triple 'do not' phrasing.

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 usefully compensates by enumerating returned fields and dictating presentation format. Only gaps are pagination/limit behavior and result ordering context beyond what the schema's sort_by text supplies.

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

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

Schema coverage is 100%, so both sort_by and include_context are fully documented in the schema. The description mentions returned fields (score, role, handle, snippet, draft) but adds no meaning to the actual parameters, leaving the schema to do all the work — the baseline 3 for high coverage.

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 states a specific verb (List), resource (lead missions), and scope filter (pending, awaiting review). An agent can distinguish this from siblings like draft_mission, approve_mission, or get_pipeline without opening any schema.

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

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

The description implies usage ('awaiting review') and gives output-handling guidance (numbered list, read directly from JSON, don't run shell commands), but it never states when to prefer this over alternatives or exclusions. The routing to draft_mission for single missions lives only in the schema parameter text, not the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: dead prospects are never to be contacted and are counted as do_not_contact, get_message_prompt will refuse them, and the response should not be introspected with shell commands.

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 and return fields are front-loaded, and the mode list is long but earns its place by defining intent semantics the agent needs. Minor verbosity in the mode prose keeps it short of 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?

With no output schema, the description compensates by enumerating the returned fields (id, handle, channel, temperature, mode, last_signal, last_contact, objections) and even prescribing the presentation order. Nothing an agent needs to call or interpret this tool is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly adds no parameter guidance because none is needed.

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

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

States a specific verb and resource ('List the prospect pipeline') plus the ordering rule ('hottest-first'). It also distinguishes itself from siblings by noting that get_message_prompt refuses dead prospects, so an agent can tell it apart from the messaging tools.

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

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

The mode definitions imply when each prospect state applies and the dead-mode note hints at downstream tool behavior, but there is no explicit statement of when to call get_pipeline versus alternatives like track_prospect or score_signal. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description adds genuine value beyond that by enumerating the returned fields and, more importantly, prescribing the presentation contract (one line per product, do not dump raw JSON). That is a real behavioral trait not available in structured fields.

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

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

Three short, front-loaded lines: purpose first, then return fields, then presentation rule. Every sentence carries information an agent needs to call and render the result correctly, with no 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?

With no output schema, the description correctly carries the return-value burden by listing the fields and format. It is complete for a zero-argument list tool, though it says nothing about ordering or result size, which is a minor gap rather than a blocker.

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 zero parameters, so the baseline of 4 applies. Nothing in the description needs to compensate for parameter documentation, and it introduces no parameter-related confusion.

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

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

States a specific verb and resource ('List configured products') and adds scope ('being monitored for buying signals'), which tells an agent this tool is distinct from write-side siblings like add_product/update_product. It does not name a sibling or spell out how it differs from reload_products, so it stops short of a 5.

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

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

Usage is implied by the read-only listing nature, but there is no explicit when/when-not guidance and no reference to alternatives such as reload_products. An agent can infer it is the browse path, but nothing in the text routes it there.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the exact fields returned, the meaning of read_by (server vs client reader), counters like posts captured vs queued vs rate-limited, and a plain-language verdict. It stops short of stating pagination or auth requirements, so it is not fully exhaustive.

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

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

Front-loaded with the purpose and scope, then a structured field inventory and presentation note. Efficient overall, though the verdict example is slightly verbose and the description runs long for a list 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?

There is no output schema, so the description correctly carries the full burden of describing the returned fields, their meaning, and the rendered presentation. An agent has everything needed to call it and interpret 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 100% and the single product_id parameter is already documented in the schema, so the description need not carry parameter burden. It adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb and resource ("List your stations (feeds)") plus a defined scope ("health readout for the last two weeks"). It also distinguishes itself from the mutating siblings by telling the agent to feed the returned ids into update_station/remove_station.

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 agent learns the ids feed update_station/remove_station, and product_id filters the scope, but there is no explicit when-to-use/when-not guidance versus siblings like preview_station or get_pipeline. Adequate but leaves the alternative selection to inference.

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

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

Annotations cover readOnly/idempotent/destructive, but the description adds substantial context beyond them: it enumerates side effects (records outreach, creates/updates the prospect, starts its lifecycle, counts as a positive endorsement for the source feed) and explains the idempotency behavior concretely, including interaction with a prior approve_mission call. The consequences of NOT calling it (mission sits unfinished, no prospect created) are also disclosed.

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 in the first sentence, and the 'What this does' and 'When to use this vs the others' sections are cleanly structured. It is somewhat long for a one-parameter tool, but nearly every sentence carries distinct routing or behavioral value.

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, so the description appropriately covers both sides: what the call changes (send recorded, prospect lifecycle started) and how to choose it over alternatives. An agent has everything needed to invoke it 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 100% and the single mission_id param is fully documented in the schema (including where to get it: get_missions). The description adds no new syntax or format detail for the parameter, so the baseline 3 applies.

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

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

The opening line gives a specific verb (mark) and resource (mission), and immediately scopes it as 'sent by hand.' It explicitly contrasts itself with approve_mission, reject_mission, and delete_mission, so the agent can distinguish it from siblings without opening any schema.

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

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

Provides an explicit when-to-use section that names the three sibling alternatives and the condition selecting each ('you sent it yourself' vs 'queue for autonomous sender' vs 'not reaching out'). It also states the timing ('the moment you've actually messaged or replied'). Nothing is left to inference.

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

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

Goes well beyond the annotations: it describes the internal process (reads feed, scores fresh posts, panel judges best-matching), the cost model (each judgement, default 8), the fixed verdict thresholds, and NO DATA failure modes. The 'Nothing is saved' statement plus the judgement consumption also explains the non-readOnly hint.

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

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

Front-loads the purpose in the first line, then covers inputs, returns, and presentation. It is fairly long, but the length is justified by the tool's complexity and every sentence carries information; minor tightening is possible.

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 compensates fully by enumerating the possible verdicts and describing the returned sample of kept/rejected posts plus how to present the result. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the description mostly restates what the schema already documents (default 8, 1-12 range, entries up to 50, rss_url or entries). Baseline 3 applies when the schema does the heavy lifting and the description adds only marginal detail.

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 ('Check whether a feed has buyers for a product') and frames the scope against a named sibling ('BEFORE adding it as a station'). An agent can immediately distinguish this from add_station without opening either schema.

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

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

Explicit when-to-use (before adding a station) and when-not (only suggest add_station for VIABLE or MARGINAL). It also routes between the two input modes, noting that feeds read on the operator's machine (read_by: client) must be sent as entries.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive behavior. The description usefully adds the daily send-cap constraint, which annotations cannot express, but it does not say what happens when the cap is hit or whether repeated calls create duplicate records despite idempotentHint=false.

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

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

Two short sentences that front-load the action and then the prerequisite and constraint. 'Daily send cap still applies' is slightly elliptical but earns its place as the only behavioral caveat.

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 description covers the prerequisite, the side effect (marks a message as sent) and the rate cap, while annotations cover the safety profile. It stops short of describing duplicate handling or downstream pipeline effects.

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% with all four parameters described, so the schema carries the parameter burden. The description adds a small amount by tying 'tactic' and 'next_step' back to the schema returned by get_message_prompt, but no field formats or constraints beyond that.

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 – recording a drafted message as sent to a prospect – which is clear on its own. It does not distinguish itself from the sibling mark_sent, so an agent must guess which of the two records a send in which situation.

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 an explicit prerequisite ('Use after get_message_prompt') and an operating constraint ('Daily send cap still applies'), which is real sequencing guidance. It omits any when-not guidance and says nothing about how it differs from mark_sent or upload_draft.

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 annotations, which only declare a non-destructive, non-idempotent, closed-world write. The description discloses that the brain updates temperature/mode/objections, that do_not_contact blocks all future messaging via get_message_prompt, and that invites_private_contact gates DM consent on Reddit/X.

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 and return semantics are front-loaded in the opening lines, and the bulleted return-value list is scannable. The trailing presentation instruction is useful but slightly beyond the tool's own behavior; overall still tight.

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 compensates by enumerating the returned fields (intent, mode, do_not_contact, invites_private_contact) and their operational meaning. Annotations cover idempotency/safety, and the two required params are schema-documented, so 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%, so prospect_id, reply_text and channel are already documented in the schema. The description adds channel context indirectly ("a comment reply, a DM, an email") but no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ("Record what a prospect wrote back") and immediately clarifies the downstream effect ("let the brain read it"). This distinguishes it from the near-name sibling record_message, which records outbound messages rather than inbound replies.

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 an explicit trigger ("Call this whenever a tracked prospect replies") with concrete channels enumerated (comment reply, DM, email). It also names a downstream dependency (get_message_prompt will refuse after do_not_contact), but does not explicitly route to an alternative tool for other cases.

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 establish the safety profile (not read-only, not destructive, not idempotent) but the description adds substantial behavior: the rejection feeds an RL penalty into the source feed's scoring weight, reason choice changes penalty size, and already_customer carries no penalty. It also warns that misusing not_relevant penalises an innocent station — well beyond annotation coverage.

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 purpose in the first line, then layers alternatives and the reason list. The closing 'Pick the most accurate reason' sentence is mild redundancy, and the reason list is long, but each block earns its place given the enum-like domain knowledge it conveys.

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 tool with no output schema, the definition covers the safety profile via annotations, the learning side-effect, the sibling boundary, the failure case, and every reason code. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by annotating each rejection_reason value with its actual semantics and relative penalty weight (spam = heaviest, already_customer = none, no_reason = default). mission_id only gets an implied source ('from get_missions') already in the schema, so it's not a 5.

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

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

States a specific verb+resource ('Reject a mission — it was not a real buying signal') and immediately disambiguates from the closest sibling, delete_mission. An agent can distinguish it from all 22 siblings without opening a schema.

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

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

Gives explicit when-to-use-vs-delete_mission contrast with a rationale (learning vs queue cleanup), plus a clear when-NOT-to-use clause for disappeared posts and the consequence of getting it wrong. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety and repeatability profile is covered structurally. The description's only added behavioral signal is that this is a cache refresh needed after mutations; it says nothing about scope (global vs per-product) or cost.

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

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

A single sentence that front-loads the action and immediately follows with the required precondition. Every word earns its place with no filler or restatement of the name.

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 no-argument, no-output-schema maintenance tool whose annotations already carry the safety profile, the description supplies the one thing an agent needs: when to call it. It could note the scope of the reload, but nothing critical to correct invocation is absent.

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

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

There are zero parameters, so per the rubric the baseline is 4; there is no parameter semantics to convey. Schema description coverage is 100% of an empty property set, so nothing is missing.

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: reload the product cache. It distinguishes itself from the read-oriented get_products by indicating it is a cache-management action tied to the mutation siblings add_product and update_product, though it doesn't name those siblings explicitly.

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?

"after adding or editing products" gives a clear trigger condition that maps the tool to the add_product/update_product workflow. It stops short of an explicit when-not-to-use statement or naming the sibling tools, but the timing guidance 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?

Goes well beyond the annotations (destructive=true, idempotent=true) by disclosing the conditional behavior: stations without lead history are truly deleted, while those with history are only paused to preserve it. It also names the exact reply values ('deleted', or 'paused' with reason 'has_history'). That is exactly the kind of outcome disclosure an agent needs before calling a destructive 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 short sentences plus a brief explanatory paragraph; the destructive action and its prerequisite are front-loaded, and every sentence carries distinct information (prerequisite, branching logic, return values).

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 compensates by explaining the response strings, and the branching delete/pause behavior removes the main ambiguity for a destructive tool. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% and the single parameter is documented there ('the station's id, from list_stations'). The description adds no further parameter syntax or format detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Remove a station') and immediately distinguishes the two possible outcomes (deleted vs. paused). An agent can tell this apart from siblings like add_station, update_station, and preview_station without opening any schema.

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

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

Explicitly states the prerequisite 'Confirm with the operator first,' which is real guidance for a destructive operation. It does not name an alternative tool for cases where the user wants a softer action, but the delete-vs-pause logic is covered inside the tool itself.

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 are sparse (readOnlyHint=false, non-idempotent, non-destructive), so the description carries most of the burden — and it does, disclosing the budget-limited panel, the `degraded`/`swarm_skipped` states, `panel_verdict` semantics (judges can raise but never lower), and that scoring consumes a per-tenant daily budget. This is well beyond what annotations convey. It stops short of the absolute top only because it never explicitly reconciles readOnlyHint=false against the description's framing of the tool as non-mutating.

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 long, but organized into clearly front-loaded sections (purpose, when-to-use, mechanism, return shape, degraded handling, presentation). The `degraded` warning is emphasized with repeated framing that borders on redundant, but almost every sentence carries operational instruction 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?

With no output schema, the description fully specifies the return payload (score, role, classification, sub-scores, competitor info, drafting_context, swarm block) and explains the conditional edge cases an agent must handle before trusting a verdict. Nothing needed to invoke and correctly interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that scoring a reply should pass the answered post/thread as `context` so judges treat it as background, matching the schema's intent, and pinpoints `product_id` (from get_products) and the tone-only effect of `source_hint`. This goes beyond the schema text.

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 states a specific verb (score) and resource (arbitrary text) plus the four classification targets it produces (buying-intent / competitor-mention / churn / noise). It also distinguishes itself from the drafting sibling by naming the `draft_mission` pattern, so an agent can tell it apart from other tools without reading a schema.

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

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

It gives explicit when-to-use conditions ('when your agent encounters content from any channel it has access to... before drafting a reply') and enumerates channels. It also provides a downstream decision rule: surface a lead for buying_intent/competitor_mention, stay quiet on noise/borderline. Alternatives and exclusions are effectively covered.

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 beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing a per-tenant rate limit (one on-demand scan per 15 minutes) and the cooldown / batch_in_progress skip reasons for a failed trigger. It stops short of saying whether a successful call blocks until results are ready or returns immediately.

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 context, then the failure mode. No filler or repetition of the title or annotations.

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

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

With no output schema, the description usefully explains the 'skipped' outcome, but it leaves the success payload ambiguous (what a started scan returns, and whether it is synchronous). For a zero-parameter trigger tool this is close to complete but not fully specified.

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

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

The tool takes zero parameters, so the schema carries no semantics to supplement. Baseline 4 applies; the description correctly implies there is nothing to configure.

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 ('trigger an on-demand scouting run') plus the scope ('across YOUR active products'), and contrasts it with the automatic 30-minute schedule. No sibling tool does scouting, so an agent can select this unambiguously.

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

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

Gives a clear when-to-use condition ('Use this when the operator wants a fresh scan now') and distinguishes it from the automatic cycle. It doesn't name alternatives, but none exist among the siblings, so no exclusion guidance is owed.

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, destructiveHint=false and openWorldHint=false, so safety is covered before the description is read. The description adds real behavioral context beyond that: the return shape {"anchors": [str, ...]}, the fact that anchors drive what posts users see, and the instruction to route output through human editing rather than trusting it directly.

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

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

Front-loaded with the imperative action and the sibling-ordering constraint, then a numbered flow, then a criteria contrast. The length is justified by the tool's high-stakes workflow role and every paragraph carries distinct information; 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?

No output schema exists, but the description supplies the return shape itself ({"anchors": [str, ...]}) plus the surrounding workflow, so an agent has everything needed to call it and act on the result. Annotations cover the safety profile and the description covers the semantic and procedural gaps.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all five parameters. The description adds meaning by mapping the pre-call questions (what the product is, who buys it, what it does) onto name/value_prop/target_audience, and by illustrating what value_prop content should look like via buyer-voice vs product-voice examples.

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 ("Generate candidate anchor sentences for a product") and immediately positions it against a sibling with "CALL THIS BEFORE `add_product`". An agent can distinguish it from add_product without opening either schema.

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

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

Provides an explicit recommended setup flow (ask three questions, call this tool, show anchors for edits, then add_product, then reload_products), which is direct when-to-use and ordering guidance naming the relevant alternatives. It also gives an explicit 'when it's easy to get wrong' rationale.

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 the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description only needs to add what they don't cover. It does: the tool creates the prospect if new (upsert semantics), and opted_out terminates the relationship. It does not describe the response payload, but that is a minor gap given annotation coverage.

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 blocks, front-loaded with the core action, then signal semantics, then the routing rule to record_reply. Every sentence earns its place; no 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 5-param mutation tool with no output schema, the description covers the important behavioral facts (upsert creation, terminal signal, sibling routing). It stops short of noting that duplicate signals are not idempotent or what the call returns, leaving a small gap an agent might want.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it enumerates signal values and interprets them (opted_out means the prospect asked not to be contacted and ends the relationship). That interpretation is genuine added value beyond the raw enum list.

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 (log a signal, update temperature) with a concrete scope, and explicitly distinguishes itself from record_reply. An agent can tell this apart from siblings like score_signal or record_reply without opening any schema.

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

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

Names the alternative (record_reply) and the precise condition that selects it: when the prospect's actual reply text is available. That is exactly the when-to-use/when-to-use-something-else guidance an agent needs.

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

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

Goes well beyond the annotations: it discloses that the previous anchor set is retained for undo, that active=false stops stations being read and halts score_signal acceptance, and that products are paused rather than deleted so history persists. These are exactly the mutation-side effects an agent needs and annotations do not convey.

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

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

Front-loaded with the core action and partial-update semantics, then compact paragraphs on anchors and pausing. Every sentence carries operative information (undo, station effects, operator confirmation) with no 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?

No output schema, but the description needn't explain returns. With 9 params at 100% schema coverage and no annotations describing side effects, the description supplies the missing behavioral contract (pause effects, undo, confirmations) and is complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: the anchor_sentences grammar (3+, each 5-40 words, BUYER describing their problem) and the side effects of active=false. It adds beyond the schema for the params that matter most.

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

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

States a specific verb+resource ('Edit a product') plus a second mode (pause/resume) in the first sentence, and clarifies the partial-update contract ('Only the fields you pass change'). This is clearly distinguishable from add_product and update_station among the siblings.

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 an explicit precondition ('Confirm with the operator before changing anchors or pausing') and routes anchor_sentences to the add_product rules, but never explicitly states when to choose this over add_product or how to create a new product instead. Clear context, no full alternative routing.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior. The description adds two real traits beyond them: partial update (only passed fields change) and pre-save validation of a new rss_url (http/https, public host). It doesn't cover failure behavior or permissions.

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, front-loaded fragments with zero filler. The operation set leads, semantics follow, prerequisite last.

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

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

For a 5-param mutation with full schema coverage and annotations carrying the safety profile, this is nearly complete: it explains partial updates, the id source, and URL validation. No output schema exists, so return-value detail is not owed.

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

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

Schema description coverage is 100%, so the schema documents all five parameters (including the rss_url validation note). The description's 'only the fields you pass change' adds meaningful update semantics, but otherwise mostly restates the schema, so baseline 3 applies.

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

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

States four specific operations (pause, resume, rename, re-point) against a single named resource (station), clearly distinguishing it from siblings like add_station, remove_station, and preview_station.

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?

'Get station ids from list_stations' gives the prerequisite, and 'Only the fields you pass change' establishes partial-update semantics. It stops short of explicit when-not guidance or naming an alternative for deletion/pausing workflows.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds meaningful state-transition detail: the mission moves to pending_approval, surfaces for operator review, and reasoning is logged to the audit log. That is real behavioral context beyond the structured fields, though it doesn't reconcile what idempotent uploads mean.

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, front-loaded with the core action and followed by the consequence. Nothing redundant; the backticked parameter name gives a useful inline pointer.

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 action, required inputs, and the resulting state change well. Minor gaps remain around error behavior and whether re-uploading replaces the prior draft (relevant given idempotentHint=true).

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's note that `reasoning` is an optional one-sentence justification largely restates the schema's own 'kept in the audit log' text, adding little beyond the documented baseline.

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

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

States a specific verb (upload) and resource (a reply draft for a mission), and clarifies the downstream effect (mission moves to pending_approval). This distinguishes it from siblings like approve_mission, reject_mission, and draft_mission, which handle different stages of the same workflow.

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 usage ('a reply draft you wrote') and explains the downstream workflow, but never explicitly names alternatives or states when to prefer this over approve_mission/reject_mission or how it relates to draft_mission. The when-to-use is left to inference.

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