ScriptGrain

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description is free to add what structured fields can't: that the page is rescored on every monthly run, that it consumes the plan's page allowance, and that it returns updated monitor state. These quota and repeat-scoring behaviors are the kind of context annotations don't carry.

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

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

Front-loaded with the purpose and cadence, then quota, then return value and endpoint. Dense but each sentence carries distinct information; the API reference URL is the only slightly expendable element.

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 covers the return value ('updated monitor state'), the side effect (counts against page allowance), the trigger cadence, and the underlying endpoint. For a 3-param mutation with annotations already handling safety, an agent has what it needs 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 coverage is 67% and the description adds little per-parameter meaning: 'against a profile' loosely maps to profile_id (which has no schema description) and 'public page' restates the url constraint the schema already documents. The 'label' parameter is never addressed, so it does not compensate for the coverage gap.

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

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

States a specific verb+resource+scope: 'watch a public page for voice drift against a profile'. The parenthetical about running on every monthly run and on run_voice_monitor implicitly separates it from the sibling that performs the run, so an agent can distinguish add_monitor_url from remove_monitor_url and run_voice_monitor.

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 concrete usage context ('the about page, pricing, recent posts, anywhere the voice is published') and clarifies the ongoing cadence (monthly run/run_voice_monitor). It stops short of stating when NOT to use it or explicitly naming remove_monitor_url as the counterpart for undoing the watch.

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-readonly, open-world, non-idempotent write; the description adds rich context beyond that—indexing on submission, verbatim quotes of 60+ words, duplicate-skip behavior, auto-linking to existing memory, default kind, and topic fallback to 'the nearest close topic'. It even names the exact API endpoints, which the annotations do not provide.

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

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

One dense paragraph, but the numbered (1)/(2) structure is front-loaded with the two-mode framing and every sentence carries information (dedup rule, char limits, default values, endpoint). Slightly heavy for a single block, but nothing is wasted.

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

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

For an 8-parameter, no-output-schema write tool, the description covers modes, constraints, dedup, linking, and endpoint references. It says little about the response shape (beyond 'it is indexed now'), which is a minor gap given there is no output schema.

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

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

Schema coverage is 88%, so the baseline is 3, but the description meaningfully clarifies the interplay among memory/kind/topic_id/topic_label (default kind, topic_id from get_memory, topic_label creates if new, neither = nearest close topic). It adds semantics the schema hints at but does not fully spell 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 (add) and resource (Voice Brain memory) and defines two distinct modes: a 'piece' via text/URL, or a single 'memory' statement. This lets an agent distinguish it immediately from siblings like get_memory, edit_memory, delete_memory, and sync_memory 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?

Explicitly frames the choice between the two modes ('one of two ways', 'instead of a piece') and routes topic resolution to the get_memory sibling and its topic_id. It does not explicitly compare against other writing siblings (edit_memory, sync_memory), so it falls short of full when-not guidance.

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

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

Annotations already declare a safe read-only, idempotent, closed-world operation, so safety is covered. The description adds that it is free and correlates with GPTZero/Originality, which is genuine extra context not carried by 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?

One dense sentence, front-loaded with the method and output, 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 single-input tool with an inline description of return fields, the definition is nearly complete. Only minor gaps remain, such as what happens with inputs under 50 words.

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 only parameter already documents the 50+ word requirement. The description repeats the word-count constraint but adds no format or syntax detail beyond the schema.

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

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

States a specific verb+resource (stylometric analysis of text) and the exact output artifact (human_score plus detected signals). Distinct from siblings like check_novelty or check_voice_match, which measure different properties of 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?

The 50+ word minimum is stated as a usage condition, which is useful. But no explicit guidance on when to prefer this over siblings like check_novelty or check_voice_match, and no when-not-to-use.

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/non-destructive, so safety is covered; the description adds real value beyond that by disclosing the cost ('Free.') and enumerating the verdict semantics ('repeats' at two or more prior pieces, 'builds_on', 'new'). It does not describe latency or failure behavior, keeping it short of 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?

Front-loads the trigger ('Before you write') and then the return shape; every clause carries information. It is dense and long for a two-parameter tool, but no sentence is idle.

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 explain returns and it does so completely: verdict values, closest prior pieces with quotes, ESTABLISHED ideas, GAPS, and up to three grounded angles. Combined with the usage guidance, an agent has everything needed to call and consume this tool.

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

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

Schema coverage is 50%: 'brief' is documented in the schema and the description adds only light framing (the brief/topic you intend to write about, plus that a chosen angle goes in it). 'profile_id' is undocumented in both schema and description. Baseline 3 is appropriate when the schema carries half the load.

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 (check) and resource (a brief against the profile's Voice Brain memory) and immediately distinguishes itself from sibling checks like check_voice_match. An agent knows exactly what this produces: a novelty verdict against prior writing.

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 names the sequence: 'Before you write... Use it before generate_content: put the chosen angle into the brief.' It states when to call it and what to do with the result, which is stronger guidance than most siblings provide.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: no credit consumed, the score_context caveat array that prevents misreading structurally low scores, the reporting rule to cite deltas rather than invent detail, and the 20+ word minimum. That is context an agent cannot get from the 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?

Front-loaded with purpose and mechanism before the return-value detail, and most sentences carry information an agent needs (thresholds, caveats, reporting rule). It runs long and has mild redundancy around the deltas/notes relationship, but nothing is pure 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, so the description correctly carries the full return-shape burden and does so: voice_match_score range, deltas array contents, notes provenance, and score_context caveats. Combined with the input constraints and usage scale, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% (baseline 3), but the description adds a real constraint the schema does not express: the schema declares minLength 1 while the prose requires 20+ words and ~50k char ceiling. It also clarifies profile_id must be a 'complete' profile, which is more specific than the schema's plain uuid format.

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 ('Score any text against a voice profile') and explains the mechanism (stylometric feature-delta measurement) in concrete terms. It is clearly distinguishable from most siblings, but never names the obviously adjacent sibling compare_voice, leaving an agent to infer which of the two to reach for.

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 use context ('verify drafts you wrote yourself and iterate') and useful scale interpretation (0.85-0.95 on-voice, 0.5-0.8 partial, <0.45 off-voice). However it offers no explicit when-not-to-use condition and does not route the agent away from compare_voice, so the guidance is clear but not discriminating.

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 safety (readOnly, idempotent, non-destructive), but the description adds substantial behavioral context beyond them: it is free/no credit consumed, prose is fetched from URLs with menus and footers skipped, inputs need 120+ words, and the score bands are calibrated with base rates. It even discloses a measured reliability limitation (brand-voice reads weak on website pages, 55% / half of pairs drifting, study SGR-009).

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 constraints before the calibration detail, and every sentence carries information (bands, output fields, study caveat, citation instruction). It is dense with parentheticals and long clauses, so it is heavier than ideal, but nothing is padding.

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

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

There is no output schema, and the description fully covers the return surface — per-piece score with calibration bands, band, top_differences, top_matches with the numbers behind each, and notes. Input constraints and the intended interpretation of the score are also covered, so an agent can call and use 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 100%, so the baseline is 3; the description earns above that by adding meaning the schema does not carry — the URL path fetches only page prose (menus/footers skipped) and the 120+ word threshold for pasted text. The '0 to 3 pieces' and label semantics are largely already in the schema, so it is not a full 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 and resource ('score up to three pieces of writing against a main piece') and immediately delimits scope with 'with NO profile', which separates it from check_voice_match. The first sentence alone lets an agent distinguish it from every 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?

Gives explicit when-to-use ('compare two writers, or a draft against a reference piece, when no profile exists') and implicitly names the alternative path via 'NO profile' plus the reference to check_voice_match's engine. It also gives a when-not nuance: pass on the score band for website pages and judge from measured differences instead.

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

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

Annotations establish only the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds genuinely new behavior: the operation is free and consumes no generation credit, url imports are restricted to paid plans, ~10 pages are read and only claims those pages actually make are used, and the call is a POST to /v1/companies.

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 action, then the three modes in parallel structure, then cost/return caveats. Dense but every clause carries information; the trailing API-reference URL is the only mildly expendable element.

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 six optional parameters and no output schema, the description does the necessary work: it explains mode selection, plan constraints, cost, and states what is returned ('Returns the company'). Return-shape detail is thin, but the caution to check extracted facts compensates for the missing output schema.

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

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

Schema description coverage is already 100%, so the schema carries the per-field meaning and the baseline is 3. The description adds value the schema does not: it maps parameter groups to named modes, clarifies that `text` accepts ANY freeform input (a pitch or rough notes), and that manual mode is the fallback when no url/text is supplied.

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 ('Create a company/product context profile') plus the downstream purpose ('company-grounded generation'), so the agent knows what artifact is produced. It does not, however, differentiate itself from the sibling create_profile, which an agent must disambiguate on its own.

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 enumerates three mutually exclusive input modes (url, text, manual fields) with the condition that selects each, and states the plan gating (url import is paid, text and manual are all plans). It also gives a procedural guideline: verify extracted facts with the user before generating.

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

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

Adds substantial behavior beyond the annotations: it is free ('consumes no generation credit'), it returns a generation_id with status 'outline', and the id tracks the piece through 'outline' → 'drafted' → 'edited'. This lifecycle contract is exactly the kind of context annotations cannot convey and is consistent with readOnlyHint=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 with the purpose, then the free-credit fact, then the id lifecycle, then the use-case guidance — a logical order with no filler sentences. It is dense and slightly long, but essentially every clause carries information, so it stops just 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 fully by describing the return value (generation_id + status) and its lifecycle, and it clarifies the free/first-step position in the pipeline. 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 description coverage is 100%, so the schema already documents all 10 parameters thoroughly; per the baseline this caps the value-add at 3. The description only references the returned id and the 'optionally edited outline' flow, adding no parameter syntax or constraints beyond the schema.

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

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

States a specific verb+resource ('Generate a markdown outline for a long-form piece') plus the scope (review structure before drafting), clearly distinguishing it from the sibling generate_content that actually drafts. An agent can tell what this produces and why 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?

Explicitly names when to use it ('Best for article, newsletter, email, press_release and other long-form types') and when not to ('short social types don't need one'), and routes forward by naming generate_content as the next step consuming the returned id.

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 establish that this is a non-read-only, non-idempotent write; the description goes far beyond that with rate limits (5 extractions/hour, one monthly plan slot), async execution with expected duration, the polling contract via get_profile, and the result field samples_used for user confirmation. It also warns the agent to tell the user which pieces are being sent before calling.

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

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

Purpose is front-loaded and every paragraph carries operational content, but the anti-AI-text rule is restated several times ('never AI-generated text', 'never your memory notes or summaries', 'never text you or another AI wrote or rewrote'), which adds length without new information.

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

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

For a mutating, asynchronous tool with no output schema, the description supplies everything needed: input validity rules, sample-count and length thresholds, rate/slot limits, escape hatch via get_billing, and the polling path to completion. Nothing an agent needs to invoke and follow up correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real constraints not present in the schema: 1-20 samples, each under 5,000 words, 50+ words minimum to count, and 3+ samples totalling 3,000+ words for a confident profile. It does not enrich the name, shared or english_variant parameters, which the schema already documents well.

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 ('Create a new voice profile from writing samples') and states the downstream effect ('start the stylometric extraction (45 measured attributes)'). An agent can distinguish this from get_profile, list_profiles and create_company without opening any schema.

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

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

It explicitly states when to use it and what constitutes valid input, including which sources are acceptable ('writing you already hold for the user') and which are not ('never your memory notes or summaries', 'never text you or another AI wrote'). It also routes the agent to siblings at the right moments: get_profile for polling status and get_billing when refused for slots.

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

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

Adds substantial behavior beyond the annotations: the authorization model (author vs. team owner/admin), the non-cascading effect ('drafts already written from it are untouched'), and an explicit confirm-with-user instruction. Annotations only supply the generic destructive/idempotent profile; the description supplies the permission and blast-radius context that matters for a destructive 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 permissions, side effects, and the confirmation cue. No sentence 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 one-parameter destructive tool with no output schema, the description covers exactly what an agent needs: what it does, who may do it, what is preserved, and that user confirmation is required. Nothing material is missing.

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

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

Schema coverage is 100% and the single parameter already documents itself as 'A template id from list_brief_templates.' The description adds no format or sourcing 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 and resource ('Delete a brief template') that is unambiguously distinguishable from siblings such as save_brief_template and list_brief_templates. 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 clear conditional context for when the call is permitted (author, or team owner/admin for shared templates) and requires user confirmation before proceeding. It stops short of naming a sibling alternative (e.g., save_brief_template for edits), so it is clear but not fully 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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing what actually gets destroyed and its downstream semantics: the deletion persists even when the source piece is re-read, and in a shared brain it removes the memory for every voice. It also adds an interactive safety requirement (user confirmation), which is exactly the kind of context annotations cannot express.

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

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

Three short sentences with no filler; the core action leads, and each following sentence adds a distinct behavioral fact (persistence, blast radius, confirmation). Nothing is redundant with the 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?

For a two-parameter, no-output-schema tool, this covers purpose, irreversibility semantics, cross-voice impact, and a safety step. The only meaningful gap is the unexplained profile_id, which the agent must infer or obtain elsewhere.

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 carry parameter meaning. It explains unit_id's provenance ('unit_id from get_memory'), which is genuinely useful, but profile_id is never mentioned, leaving one of two required parameters undocumented.

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

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

States a specific verb (delete) and scoped resource ('one memory'), and points at get_memory as the source of the id, which helps the agent distinguish deletion from retrieval. It does not, however, differentiate from the more confusable siblings edit_memory or forget_piece, so sibling selection still requires inference.

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 purpose plus the procedural directive 'Confirm with the user first', which is a real prerequisite. But it never states when to choose this over edit_memory (modify) or forget_piece, so guidance on alternatives 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine beyond-annotation context: the change feeds novelty and what_next, and is preserved when the source piece is re-read. It leaves implicit that rewording discards the prior text, but the downstream effects are real added value.

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

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

One dense sentence front-loads the verb and then packs the mutation options into parentheticals; every clause carries information. The nested parentheses make it slightly harder to scan than a flatter structure would.

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 6-param mutation tool with no output schema, the description covers the meaningful parameters, id provenance, the at-least-one rule, and downstream effects. Remaining gaps (profile_id, whether prior text is recoverable) are minor against annotations that already signal destructiveness.

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 carry parameter meaning, and it does: text='reword it', kind='change its kind', topic_id/topic_label with null and find-or-create semantics. Only profile_id is left unexplained, and its role is inferable from context.

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

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

States a specific verb and resource ('Change one memory') and enumerates the three exact mutations available: reword via text, change kind, or move topics. It anchors unit_id and topic_id to get_memory, distinguishing it from add_to_memory and delete_memory without needing 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?

'Send at least one' gives the key precondition, and it names get_memory as the source of unit_id/topic_id, plus the null-vs-label semantics for topic. It stops short of explicitly contrasting with the sibling it displaces (add_to_memory for new units), but the context for when to call it is 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new consequence detail: a draft/sample/watched page is never re-imported while a pasted piece is deleted, which tells the agent how permanent the effect is per source type.

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 the destructive scope, then the source-type consequence, then the confirmation prerequisite. No filler and no repetition of the title.

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

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

For a destructive two-parameter tool with no output schema, the description covers scope, permanence by source type, and the user-confirmation requirement. The remaining gap is the undocumented profile_id parameter and any indication of what the caller gets back after the delete.

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 for both parameters. It usefully explains where item_id comes from (get_memory) but says nothing about profile_id, leaving one of two required parameters with no semantics in either place.

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 ('Forget a whole piece ... and every memory taken from it') and clarifies the unit of deletion, which distinguishes it from the sibling delete_memory that acts on a single memory. The parenthetical 'item_id from get_memory' ties the input to the tool that produces it.

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

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

Gives an explicit prerequisite ('Confirm with the user first') and the scope rule that makes this the right tool when an entire piece, not one memory, is being removed. It does not name delete_memory as the alternative for single-memory removal, so the routing is implied 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false; the description goes well beyond that with credit costs by length tier, per-variant charging, background section-by-section writing above 4,000 words, the 'generating' status and get_job/get_generation polling loop, and the status transition to 'drafted'. It also discloses server-side variant diversification and the within_tolerance contract the caller must check.

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, then modes, response fields, costs, and long-draft behavior in a logical order. The dense stacked-parenthetical style risks overloading a single read, but nearly every sentence carries a distinct operational fact essential for a 13-parameter, dual-mode 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 return contract — voice-match score, word_count/word_count_target/within_tolerance, variant_axis, and status — and covers costs, background execution, and the polling alternative. Nothing an agent needs to invoke 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 adds mode-dependent semantics the schema cannot express: which parameters are ignored when generation_id is set, that the outline's word_count_target is honoured automatically but can be overridden here, and the meaning of the variant axes. It stops short of re-documenting fields the schema already covers thoroughly.

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 states a specific verb and resource ('Generate a finished draft in the user's measured voice') plus the automatic voice-match scoring behavior. An agent can distinguish this from siblings like create_outline, polish, humanize, and mimic_brand 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?

It explicitly defines the two mutually exclusive modes — one-shot (profile_id + brief + content_type) versus from an approved outline (generation_id with status 'outline' from create_outline) — and states that the one-shot fields are ignored in outline mode. It also adds an explicit when-not ('Don't loop this tool speculatively — confirm with the user before generating many variants, long drafts or re-generating').

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 safety is covered; 'read-only' largely repeats the annotation. The one genuinely additive detail is that the call is free, plus the disclosure of what data is exposed (credits breakdown, cancel flag). Adequate but not rich beyond 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?

Two sentences, front-loaded with the resource and its returned fields, followed by the usage trigger. The field enumeration is dense but each item is meaningful; no filler sentences.

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 parameters, the description carries the burden of telling the agent what comes back, and it does so by listing the concrete fields (plan, cycle, credit buckets, extraction usage, renewal, cancel status). Only minor gaps remain, such as nothing about error or empty-account behavior.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and schema coverage is trivially complete.

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 ('Show') and resource ('the account's ScriptGrain subscription') and enumerates exactly what is returned: plan, billing cycle, status, credits, extraction usage, renewal, cancel flag. An agent can distinguish it from list_generations, get_invoice, or upgrade_plan 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?

Gives two concrete triggers: when a generation was refused for credits, and before suggesting an upgrade. The latter implicitly routes the agent toward upgrade_plan, but no alternative is named explicitly, so it falls just short of a full when/when-not statement.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes well beyond that by defining each lifecycle state's meaning, noting that 'content holds the sections delivered so far' during a background write, and disclosing that a job object with progress and credits charged appears only when a background job wrote it — real behavioral context an agent could not get from the 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?

Front-loads the action and scope, then spends its second sentence on the status-check caveat that matters most for correct invocation. The parenthetical status glossary is dense and slightly listy, but each element maps to a distinct return field that would otherwise be undocumented given there is no output schema.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly — naming the fields an agent will act on and interpreting the lifecycle states. The single input parameter is fully covered by the schema, so nothing material is missing.

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

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

Schema description coverage is 100% and the single parameter's origin ('from list_generations or generate_content') is already stated in the schema description. The prose adds no syntax, format, or constraint detail beyond that, so the baseline 3 for full schema coverage 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 ('Fetch one past generation in full') and enumerates exactly what is returned: lifecycle status, content, outline, brief, word count, word_count_target, voice-match score, and a job object. This clearly separates it from siblings like list_generations and list_draft_versions, which are collection-oriented.

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 warns to 'Check status before acting on the content' and explains the operative conditions ('outline' has no draft to polish or edit; 'generating' is unfinished), which effectively routes the agent to polish/edit only for complete drafts. It does not, however, name a sibling tool to use instead or contrast itself with list_generations for discovery.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine value beyond the annotations by disclosing the edge-case return (no_billing_account when there has never been a paid subscription) and confirming the call is free.

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 sentence, front-loaded with the resource, then the returned fields, then the edge case. No filler or repetition.

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

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

There is no output schema, so the description carries the burden of describing the return surface, which it does by listing fields and the no_billing_account condition. It is complete enough to invoke correctly, though it does not describe the web/PDF link lifetimes or the no_billing_account shape.

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

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

The tool takes zero parameters, so there is nothing to document; the baseline for a zero-param tool is 4. The description correctly adds no misleading parameter claims.

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 (Fetch) and resource (the account's latest ScriptGrain invoice), then enumerates the exact fields returned (number, amount, status, dates, web link, PDF). An agent can distinguish it from get_billing because it is scoped to the single latest invoice.

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 context ('Free and read-only', latest-invoice scope) but never states when to choose this over the sibling get_billing, nor any exclusion conditions. 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?

Far exceeds the read-only/idempotent annotations: it enumerates every status value, explains partial-delivery behavior ('a job that stopped part way keeps what it delivered'), discloses credit semantics ('charged as words are delivered, never above the tier asked for'), and gives throughput expectations. Nothing about runtime behavior is left implicit.

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?

Dense but front-loaded: it leads with scope, then status semantics, then result shape, then polling advice. Every sentence carries information, though the single-block paragraph could be broken up for faster scanning.

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 carries the full burden of describing return values and does so: status enum, sections done of total, words written, credit cap and charges, and what 'result' holds on success. An agent has everything needed to interpret a 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?

Schema coverage is 100% and the single parameter is fully documented in the schema as 'job.id returned by generate_content, polish or humanize.' The description restates the same origin-tool information without adding format, validation, or lookup detail beyond the schema.

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

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

Names a specific verb and resource ('Check a background job') and immediately scopes which jobs it covers: long drafts from generate_content (>4,000 words) or polish/humanize (>3,000 words). This distinguishes it cleanly from get_generation and list_generations, which handle finished/finished-draft artifacts.

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 routing: use get_generation to read the actual draft once a job succeeds. It also tells the agent how often to call it ('poll every 30-60 seconds rather than in a tight loop') and why, which is exactly the operative guidance for a polling 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description earns extra credit by disclosing that every unit carries a verbatim quote and instructing to cite rather than paraphrase, plus the cost attribute ('Free'). It omits output size/pagination behavior, keeping it below 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 front-loaded with the definition, then the return contents, then usage and cost, in a dense, low-waste structure. Slightly long, but every clause (repeat counts, context, quote-citation instruction) adds selection or invocation 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?

With no output schema, the description correctly compensates by detailing the returned categories and their counts, and it is complete for calling the tool. The only gap is that the required profile_id parameter and any empty-memory behavior are never described.

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

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

The single parameter (profile_id) has 0% schema description coverage, so the description must carry the burden. It only implies profile scoping via 'this profile's writing' and never names or explains profile_id, though the parameter is a self-evident required UUID.

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

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

The description states a concrete verb (get/return) and resource ('Voice Brain') and then enumerates the exact payload: recurring ideas with repeat counts, stories, claims with context, frameworks, and topic counts. An agent can distinguish this read tool from the mutating memory siblings (add_to_memory, edit_memory, delete_memory) without opening schemas, though no sibling is named outright.

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 trigger conditions: 'Use it before drafting to build on established ideas and avoid repeating them' and 'to answer \'what have I written about X?\''. There are no when-not conditions or named alternatives (e.g. check_novelty, list_brains), so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: conditional return values (progress_percent while extraction runs, narrative plus 45 attributes once complete), null semantics for company_id, and a polling cadence. This is exactly the kind of state-transition detail the annotations cannot convey.

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

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

Three sentences, all front-loaded and free of filler; the return-value description and the polling instruction each pull their weight. The middle sentence is dense, packing several conditional returns into one clause, which slightly hurts scannability.

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 carries the full burden of describing returns and does so well, including the two states of the profile and the company_id null case. It does not cover error behavior (e.g., unknown or still-queued profile), which is the one remaining gap for a polling-oriented getter.

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 profile_id parameter is already documented in the schema, including its UUID format and origin (create_profile or list_profiles). The description adds no syntax or format detail beyond what the schema provides, 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 and resource ('Fetch one profile's status and detail') and scopes it to a single profile, which cleanly separates it from siblings like list_profiles and create_profile. An agent can identify what it returns 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 concrete workflow guidance: poll every ~10 seconds after create_profile, which tells the agent exactly when this tool is the right call. It does not explicitly state when not to use it or name list_profiles as the alternative for retrieving many profiles, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses the paid-plan gating, the tier page limits, and the interior structure of the response (per-page calibrated voice match, band, numeric top_differences, unchanged-since-last-run flag, prior-run comparison, triggerable-now state).

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 noun phrase that identifies the resource, then a single dense enumeration of returned fields — no redundant restatement of the name. It is somewhat overloaded as one run-on sentence, and the truncated trailing 'Free.' costs a little polish.

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 must carry the return-shape burden, and it does so in detail (scores, bands, diffs, comparison run, trigger state). Combined with the plan-gating prerequisite, an agent has nearly everything needed; only the truncated free-plan clause leaves a small hole.

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 one parameter exists and schema description coverage is 100%, with the schema itself explaining that profile_id must be a 'complete' voice profile id. The description reinforces the profile framing but adds no syntax, format, or constraint 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?

The description opens with a concrete resource and scope ('Voice monitor state for a profile') and enumerates the specific payload an agent will get: watched public pages, plan allowance, latest run with per-page scores and top_differences, previous run, and trigger availability. That distinguishes it from write-side siblings such as run_voice_monitor and add_monitor_url, though it never uses an explicit verb like 'retrieve' or 'read'.

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 supplies a real usage constraint — paid plans only, with per-tier page allowances — which tells the agent when the call will succeed. However, it gives no explicit guidance on choosing this over run_voice_monitor or check_voice_match; the trailing 'Free.' is a dangling, evidently truncated clause that leaves the free-plan behavior unclear.

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?

Discloses substantial behavior beyond the annotations: credit costs tiered by length, the free skip path, the >3,000-word background/async job flow with get_job polling, and the drift tension with polish. Annotations (non-read-only, non-idempotent) are consistent with a credit-charging mutating rewrite.

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 layers cost, async behavior, and ordering guidance in one dense but well-ordered block. Nearly every clause carries distinct operational value, though the run-on structure could be split for 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 complex tool with credit accounting, async jobs, and sibling interactions, and with no output schema, the description fully covers the return shapes (final text, before/after scores, remaining signals, or a job + status). 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 coverage is 100% so the baseline is 3, but the description adds real meaning — credit cost tied to text length, what force overrides, and the requirement that generation_id reference a drafted (not outline/generating) piece. It reinforces rather than merely 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 precise verb+resource (iteratively rewrite text to remove measurable machine-writing tells) and names the specific mechanisms (evened-out sentence lengths, symmetric hedging). An agent can immediately distinguish it from siblings like ai_detect, polish, and check_voice_match.

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 routing: when to use force, when it free-skips (<=3,000 words already clearing target), and critically how to sequence against a sibling — 'run polish FIRST and humanize last, then verify with check_voice_match'. This is richer than most definitions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, and the description adds real value on top: the scope of the result ('its own and every other brain on the account'), the return shape ('each with the voices that share it'), and cost ('Free'). It does not cover pagination or ordering, but the added context is substantive.

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 leading clause is well front-loaded, but the remainder is a long conceptual digression about brain-sharing tradeoffs that reads like rationale rather than operational guidance. For a one-parameter list tool this is more text than the task 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 full annotations and no output schema, the description carries the burden of describing what comes back, and it does so ('its own and every other brain on the account, each with the voices that share it'). The unexplained profile_id parameter is the main remaining 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?

Schema description coverage is 0% and the single parameter (profile_id, uuid) is never mentioned in the description. 'This voice' loosely maps to profile_id, but nothing clarifies that this is the profile identifier or its format, so the description fails to compensate for the schema 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 first clause states a clear verb and resource ('List the Voice Brains this voice may use') and scopes the result to the voice's own brain plus every account brain. The contrast with the sibling set_voice_brain is inferable but never stated, so differentiation relies on the agent's own reasoning.

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 explains what brains are and how sharing affects novelty checks and what_next, which implies this is a discovery/inspection call before setting a brain, but it never states when to call it versus alternatives. Usage 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, idempotentHint and destructiveHint=false, so 'read-only' is largely redundant. The description nonetheless adds genuinely new behavioral facts not in annotations: the sort order (most recently used first), the visibility scope (own + team shared), and that the call is free.

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 with the scope and ordering front-loaded, then the payload description, then the routing hint. 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 usefully enumerates what each returned template holds (content type, topic, angle, audience, register, key points, extra direction, length), and annotations already cover the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description does add the useful cross-tool convention that a template's id is passed as template_id elsewhere, but there are no input parameters to document.

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 (list brief templates) with explicit scope: the user's own plus team-shared templates, returned most-recently-used first. It is immediately distinguishable from save_brief_template and delete_brief_template.

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

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

Explains the downstream purpose clearly — pass a template's id as template_id to create_outline or generate_content — which tells the agent why it would call this tool. It does not, however, state when not to use it or contrast it against any alternative listing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds real context by disclosing the returned fields and the empty-list state that warrants create_company. It does not describe pagination or ordering, so it falls short of 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?

Front-loaded with purpose and payload fields, then the cross-tool wiring. It is dense but every sentence carries information; the final create_company sentence is the least essential yet still actionable.

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 listing the fields returned, and it covers the empty-list case and default-company semantics. An agent has everything needed to call this tool 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?

The tool takes zero parameters, so the baseline is 4. The description's discussion of company_id concerns other tools rather than this one's schema, but it usefully clarifies the default-company resolution behavior an agent will encounter immediately downstream.

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 user's company/product context profiles') and even enumerates the returned fields (id, name, summary, audience, key facts). It does not explicitly distinguish itself from the sibling list_profiles, which is a minor differentiation gap given how closely named the two are.

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?

Highly explicit: it names the downstream tools that consume company_id (create_outline, generate_content), states the omit-to-use-voice-default and pass-null-for-none semantics, and routes to create_company when the list is empty. Nothing about when to use this tool is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so the description's 'read-only' is largely redundant. It does add genuinely new behavior: the 50-item cap, newest-first ordering, the retention trigger (only on text replacement), and 'Free' (a cost trait not present in 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?

Front-loads the action and constraints ('List the earlier texts... newest first (up to 50)'), then adds only the retention rule and returned fields. Three sentences, each carrying distinct information, no padding.

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

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

For a one-parameter read-only tool with no output schema, the description compensates well by naming returned fields (replaced_at, word_count, voice_match_score, full content), the item cap, ordering, and cost. Nothing needed to call it correctly is missing.

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

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

Only one parameter (generation_id) and schema description coverage is 100%, so the schema already fully documents it and the description adds nothing about the parameter. Baseline 3 is correct when the schema does all the work.

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 (list) and resource (a draft's earlier versions/texts) plus scope details (newest first, up to 50). This clearly distinguishes it from list_generations, though it never names the closely related sibling restore_draft_version, which is the natural counterpart for actually reverting.

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 real context on when results exist: a version is created on hand edit, paragraph rewrite, polish, humanize, AI-tell repair, or redraft. That tells the agent what history is retrievable, but there is no explicit when-not or pointer to restore_draft_version for acting on a listed version.

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 safe read-only/idempotent profile, but the description adds real behavioral context: result ordering, the meaning of each lifecycle status value (including that 'generating' means asynchronous background work), and per-row fields. With no output schema, this disclosure of return semantics is genuinely load-bearing.

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 purpose and ordering before filters and return shape, with no filler sentences. It is dense and slightly run-on in the return-field enumeration, but every clause carries usable information.

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

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

No output schema exists, so the description must carry return-value semantics, and it does — row fields, status meanings, and where to get full content. Combined with 100% schema coverage for inputs, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all three filters and the limit bounds are already documented in the schema. The description restates the filters and the 1-50/default-20 range without adding format or selection nuance beyond what the schema provides, 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?

States a specific verb and resource ('List past generations') plus the sort order ('most recent first'), which is scope information an agent needs. It also distinguishes itself from get_generation by naming that sibling for full-content retrieval.

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 routes the agent to get_generation when full content is needed, which is a concrete when-to-use-vs-alternative condition. It stops short of saying when not to use this tool (e.g. browsing vs. targeted retrieval across unrelated list_* siblings), so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds real behavioral context beyond them: the 100-item cap, most-recent-first ordering, and the constraint that only status 'complete' profiles are usable for generation. Return-field disclosure is a bonus since no output schema exists.

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

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

Three tight sentences: scope and ordering first, return shape second, actionable constraint about 'complete' status last. No filler, nothing repeated from the schema or annotations.

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

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

With zero parameters, no output schema, and annotations already covering read safety, the description supplies everything an agent needs: the credential-scoped contents, the cap, the sort order, the returned fields, and the 'complete' status prerequisite for downstream generation calls.

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

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

The tool takes zero parameters, which sets the baseline at 4. The description's listing of returned fields (id, name, status, confidence_score, sample_count) is return-value information rather than parameter semantics, so it neither raises nor lowers this dimension.

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 voice profiles') and precisely scopes what is returned (the key's organisation profiles plus the key owner's personal ones), which distinguishes it from the singular sibling get_profile. An agent can identify the tool's role without opening the schema.

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

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

The scope sentence makes clear when this tool applies (enumerating everything the credential can access) and implicitly routes single-profile lookups to get_profile. It does not name alternatives or exclusions explicitly, so it stops short of a 5.

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

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

Annotations only mark this as non-read-only, non-destructive, non-idempotent, and open-world; the description goes far beyond that by disclosing credit consumption, expected duration, a rate limit of 3/hour, the consent gate, the 0.85 confidence cap, that scraped excerpts are persisted as profile samples, and the underlying POST /v1/mimic 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?

Front-loaded with the purpose, then layered with operational facts. It is a dense paragraph with no filler sentences, though the API endpoint and docs URL are marginally redundant for an agent choosing a 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?

With no output schema, the description covers what the agent needs: what gets produced (a ready-to-use profile with anchored samples), how long it takes, what it costs, and the consent prerequisite. Nothing material about 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?

Schema coverage is 100%, so both parameters are already documented. The description still adds meaning the schema lacks: the site must be PUBLIC and it will scrape up to 8 pages from the given URL, and it spells out the consent workflow (obtain explicit user acceptance, then pass consent=true).

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 ('Build a voice profile from a PUBLIC brand website') and details the mechanism (scrapes up to 8 pages, runs stylometric analysis, saves a profile). This clearly separates it from siblings like create_profile or compare_voice, which would not start from a live website.

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 concrete context for use: a public site URL, a 1-2 minute runtime, a 3/hour rate limit, a credit cost, and a hard precondition (user must accept the inspired-by terms before consent=true). It does not, however, name an alternative tool for building a voice from non-website sources (e.g. create_profile), so routing between siblings 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 only declare the safety profile (non-readonly, non-destructive, non-idempotent), so the description carries most of the burden and does it well: credit costs by word band, free skipped:true path, 3-pass cap, background processing over 3,000 words with status 'processing' and a get_job follow-up, and save semantics. It stops short of describing the delta/return structure, but coverage is otherwise rich.

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?

Long but densely packed and front-loaded with the core mechanism before edge cases and costs. Nearly every sentence carries operational detail (statuses, credits, job flow, humanize ordering); it is verbose but not 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 multi-mode, paid, potentially asynchronous tool with no output schema, the description covers modes, prerequisites, cost, async return path, persistence, and the sibling-ordering constraint — everything an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real value: it clarifies the two mutually exclusive modes (text + profile_id vs generation_id, with generation_id 'preferred'), notes save only applies in generation_id mode, and restates the default target of 0.9 beyond the schema's minimum/maximum.

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 (auto-polish) and resource (draft) with a precise target mechanism: measured against a profile, divergences drive revision, re-measured up to 3 passes. This clearly distinguishes it from siblings like humanize, generate_content, and check_voice_match.

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 says when to use it ('after generate_content when the score falls short, or on any text with profile_id + text') and states the prerequisite status ('drafted' or 'edited') plus the failure mode ('outline' returns no_draft). It also resolves the ordering tension with humanize.

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, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Past results are kept' clarifies the blast radius of the destructive operation, and the id source hint is an extra. It doesn't cover reversibility or permission requirements.

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 plus a short clause; the core action is front-loaded and there is no wasted wording.

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-param destructive mutation with no output schema and zero schema descriptions, the description handles the id source and retention behavior but leaves profile_id and permission/error behavior undocumented. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry the full burden. It explains url_id's origin (get_voice_monitor) but says nothing about profile_id, leaving one of two required UUIDs completely opaque.

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 ('Stop watching a page') with a clear scope, and the implicit contrast with the sibling add_monitor_url is easy to infer. It stops short of naming the sibling outright, so it lands at clear-but-undifferentiated rather than a top score.

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 by telling the agent where the id comes from ('url id from get_voice_monitor'), which is real precondition context. However, it offers no explicit when-to-use/when-not or fallback guidance beyond that single hint.

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

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

Adds rich context beyond the annotations: the replaced text is itself preserved as a version so the restore is undoable, the operation is refused during in-progress writing, the response shape matches get_generation, and it is free. These properties reconcile and extend the declared destructiveHint=false / idempotentHint=false hints.

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, each carrying distinct information (effect, undo semantics, refusal condition, return shape), with the primary effect front-loaded and the 'Free.' note ending cleanly.

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 stating the return mirrors get_generation, and it covers the mutation's reversibility, failure mode, and cost. 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 100%, and the schema already documents both uuid parameters (including that version_id comes from list_draft_versions). The description adds nothing about parameter format or selection, 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 (restore), resource (an earlier version of a draft) and the effect (becomes the draft's text, with its score). This clearly separates it from list_draft_versions (which enumerates versions) and get_generation (which it cites only as a return-shape reference).

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 concrete precondition that acts as a when-not rule: 'Refused while a long draft is still being written.' It does not name alternative tools or explicitly say when a restore is preferable to other actions, so it stops short of full routing guidance.

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

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

Annotations only cover the safety/mutability profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds substantial behavioral context on top: per-word credit cost, the 6,000-word refusal threshold, 10-90s latency, preservation guarantees for headings, facts, prices, legal lines and button labels, the ±20% length constraint, and the exact backend 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?

Front-loaded with the core action, then layered with constraints, cost, latency, output shape, and presentation guidance — essentially every clause carries information. It is a single dense paragraph that runs long, so it is efficient but not maximally scannable.

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 compensates fully by listing the return payload (ordered blocks with original + rewritten, whole-page markdown, voice-match and AI-tell scores before and after). With annotations covering safety and the description covering cost, limits, latency, and returns, an agent has everything needed to call and present this tool 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 67% and the schema already documents url and continuity in detail. The description only implies profile_id via 'the profile's voice' and says nothing about the continuity flag, so it adds marginal meaning beyond the structured fields — 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 ('Rewrite a public web page's copy in the profile's voice, block by block') and scopes it to public pages with the page's own context used as prompt material. An agent can distinguish this from humanize, polish, or generate_content 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?

Gives concrete gating conditions: paid plans only, pages over 6,000 words refused, and it tells the agent how to present results ('Show the user a few before/after blocks, not the whole deck'). It never names an alternative sibling (humanize, polish, mimic_brand) or states when not to use this tool, so it stops short of 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?

Goes well beyond the annotations (which only flag non-read-only, non-idempotent, open-world): it discloses per-page judge-call cost, that unchanged pages carry their score over, a monthly rate limit, the scheduling cadence, that the call is free of generation credit, and a latency estimate. That is exactly the extra context annotations cannot convey.

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

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

A single dense paragraph that front-loads the action and scope, then layers quota, cost, output and latency. Every sentence carries information, though the parenthetical about judge calls and carried-over scores makes the middle slightly packed.

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 still names what comes back (run summary, per-page results, refreshed state), covers cost, latency and the monthly quota, so an agent has everything needed to decide and call correctly.

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

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

Only one required parameter (profile_id, uuid) with 0% schema description coverage, and the description adds only the phrase 'for a profile.' It does not say how to obtain a profile_id or whether it accepts a name, but with a single self-evident identifier the gap is small.

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 ('Run this month's voice monitor now for a profile') with explicit scope. It is clearly distinguishable from the sibling get_voice_monitor (retrieval) and add_monitor_url (page management) 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 supplies the key usage constraint: 'One run per profile per calendar month; the scheduled run happens on the 1st,' which tells an agent this is a manual override of a scheduled job and that a second call in the same month is likely rejected. It never explicitly names the alternative for reading past results (get_voice_monitor), so it stops short of a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds genuinely new behavioral facts: the minimum content requirement, that share_with_team targets the API key's team workspace and the key must belong to one, and that the operation is free. It does not note that repeated calls (idempotentHint=false) create distinct templates, which is the one remaining behavioral 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 sentences, front-loaded with what the tool does and what it produces, followed by prerequisites and the sharing/cost notes. No filler and no repetition of schema-declared field meanings.

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 10 parameters, no output schema and annotations already covering the safety profile, the description supplies the pieces an agent actually needs: the minimum content requirement, the sharing constraint, and cost. It omits any indication of what is returned (e.g. a template id) and duplicate-creation behavior, but neither is critical 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 goes beyond the schema by adding the cross-field validation rule (at least one of topic / key_points / extra_direction) and the constraint that team sharing only works if the key belongs to a workspace. That is meaningful semantics the schema fields alone don't express.

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

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

The description gives a specific verb+resource ('Save a brief as a named template') and clarifies what a template is by pointing at the app's Brief panel, which separates it from siblings like generate_content and create_outline. It stops short of explicitly naming the adjacent list_brief_templates / delete_brief_template siblings, so it's clear rather than fully differentiated.

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

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

It states a real prerequisite ('needs at least a topic, key points or extra direction') which helps an agent decide whether the call will succeed. However, it gives no when-to-use-vs-alternative guidance — nothing about when to template versus generating directly, or how this relates to the other brief-template tools.

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

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

Goes well beyond the annotations by disclosing the status transition ('drafted' -> 'edited'), the replace-on-resave behavior, the downstream voice-learning effect of the diff, and the cost ('Free'). Annotations already declare idempotent/non-destructive; the description enriches this with operational context.

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

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

The primary action is stated first, then conditions, then side effects and cost in tight parentheticals. Dense but every clause carries necessary 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 carries return-value burden and does so by explaining the resulting status and the diff/learning consequence. Preconditions, side effects, idempotency, and cost are all covered for a 3-param mutation tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it clarifies voice_rating rates the ORIGINAL draft (not the edit) and that generation_id must reference a 'drafted' generation. This adds real state semantics beyond the field descriptions.

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 ('Save the user's FINAL edited version of a generated draft') and distinguishes itself from siblings like restore_draft_version and list_draft_versions by scoping to the final edited version. An agent can tell exactly what this does.

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

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

Gives explicit when-to-use ('when the user has finished editing a draft and is happy with it') and states a hard prerequisite (generation must have status 'drafted', not 'outline'). It doesn't name competing tools such as restore_draft_version as alternatives, so it stops just short of 5.

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

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

Annotations already declare idempotent=true, destructive=false, readOnly=false, and openWorld=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the default value ('avoid') and the downstream effect on drafting and on how check_novelty reports repeats. It just doesn't describe 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?

The setting is front-loaded before the value semantics, and every clause carries information the schema lacks. It is somewhat dense in the second half but wastes no sentences.

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-without-output-schema tool, the description covers purpose, default, and downstream behavior adequately. It omits only the return shape and any permission requirements, which is a minor gap given annotations signal an idempotent, non-destructive write.

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

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

Schema description coverage is 0%, so the description must compensate. It does so for repeat_policy by spelling out the meaning and consequence of both enum members and flagging 'avoid' as the default. profile_id is left undescribed, though its purpose is self-evident from the format and name.

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 ('Set whether similar content is allowed for a profile'), with per-profile scope made explicit. It implicitly distinguishes itself from check_novelty, which the description names as the reporter rather than the setter of repeats.

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 when each value is appropriate: 'avoid' steers drafts away from restating prior arguments, while 'allow' suits voices where repetition is the point (a brand line, a campaign). It does not explicitly state when not to use this tool or route the agent to alternatives, so it stops short of the top score.

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 flag destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so safety is covered. The description adds genuine effect semantics beyond that: joining carries the voice's memory along, and a null brain_id copies the shared memory so nothing relied on disappears, plus a same-account/team constraint.

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 action, then adds the null semantics and safety constraints. Every clause earns its place, though the sentences are dense enough that it is more thorough than minimal.

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 rich annotations already present, the description covers behavior, constraints, and confirmation procedure adequately for a 2-param mutation. The unmapped profile_id is the only notable 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?

Schema coverage is 0%, so the description must carry the load; it does this well for brain_id (uuid from list_brains vs null detach and its copy semantics). profile_id is never mapped to "the voice," leaving one of two parameters to inference despite the low 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?

States a specific verb and resource ("Move a voice to another brain") and immediately scopes it against the sibling that supplies brain_id (list_brains). An agent can tell what this does and how it relates to list_brains 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 clear context: use brain_id from list_brains to join, pass null to give the voice its own brain, and only same-account/team brains qualify. Also instructs the agent to confirm with the user first. Lacks an explicit when-not-to-use beyond the account/team restriction.

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=false, idempotentHint=true, destructiveHint=false), and the description adds real context beyond them: it is free (no generation credit), takes a few seconds per new piece, and only reads new/changed pieces once. Error behavior and what the index looks like afterwards are left implicit.

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 with no filler; the core action and its incremental nature come first, then cost and timing. The second sentence is a long compound clause, but each element (cost, duration, sequencing) earns its place.

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

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

For a single-parameter, no-output-schema tool, the description covers what it does, its cost, its duration, and the correct next call. Missing only the profile_id semantics and any failure/edge-case behavior, which are minor given the simple contract.

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?

One required parameter with 0% schema description coverage, so the description carries the burden but only implies scope via 'the profile's latest drafts and samples'. It never states that profile_id selects which profile's pieces are synced, leaving the single parameter 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?

States a specific verb and resource ('Bring the Voice Brain up to date... each new or changed piece is read once'), and the incremental, one-pass indexing behavior distinguishes it from the manual add_to_memory sibling. It also names get_memory as the follow-up read, so an agent can place it in the workflow 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 timing ('run it after finalising drafts, then call get_memory'), which is actionable sequencing. It does not state when NOT to use it (e.g. versus add_to_memory for a single piece), 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds crucial context the agent can't get from them: the tool itself never modifies the subscription or charges anything, everything completes on Stripe's hosted pages, and links expire after a few minutes. This is exactly the added value expected beyond 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?

The most important facts (secure link, no direct mutation) are front-loaded and each sentence earns its place. It is slightly dense with parenthetical pricing detail, but nothing is redundant.

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

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

With no output schema, the description still tells the agent what is returned (a shareable link) and its expiry behavior, and it covers both modes and the auto-routing edge case. Nothing needed to call this correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning not present in the schema: concrete plan tiers with prices (£12/£29/£99/£299) and the ~20% annual saving plus the monthly default for billing_cycle. The enum values themselves are already in the schema, so it stops short of 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 description states a specific verb and resource — 'Get a secure Stripe link' for upgrading or managing the ScriptGrain plan — and cleanly separates the two modes (checkout link vs billing-portal link). The sibling get_billing is distinguishable because this tool mints an upgrade/manage link rather than reading billing data.

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

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

It gives explicit when-to-use conditions: pass plan when a free account hits a credit wall, omit plan to manage an existing subscription. It also names a routing rule (already-subscribed accounts asking for checkout are sent to the portal), leaving little to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that: it discloses the return shape (angles with reasons plus established/thin/stale lists) and notes the call is Free, which 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?

The agent-facing question is front-loaded, followed by the mechanism, the return values, and the follow-up action. It is dense and slightly verbose in the middle clause, but every sentence carries usable information.

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

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

There is no output schema, so the description correctly takes on describing the return (angles with reasons plus the established/thin/stale lists) and the downstream handoff to generate_content. Given a single-parameter, low-complexity tool, this is nearly complete.

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

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

Schema coverage is 0% for the single profile_id parameter, and the description only implies its meaning through 'the profile's Voice Brain memory'. With one obvious parameter and no enum or nested structure, the baseline is met but the description adds little explicit parameter guidance.

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 function: proposing five content angles from the profile's Voice Brain memory. It names the sibling it feeds into (generate_content), so an agent can tell it apart from the raw generation tool. It is somewhat flowery but the core verb+resource is unambiguous.

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

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

Opens with the triggering question ('What should I say next?') and closes by directing the agent to pass a chosen angle to generate_content as the brief or angle field, giving clear context and a named next step. It does not state explicit exclusions, but the workflow is clear.

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