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

With no annotations, the description carries full burden and handles it well: it discloses that an empty image_style triggers an interactive prompt that waits for the user, that missing style causes save_and_present to refuse the pack, and that gemini_image_prompt strips brand names. These are non-obvious behaviors an agent must know to act correctly.

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

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

The description is longer than typical but every sentence carries value. It front-loads the purpose and return values, then dives into the critical image_style rule and param guidance. It could be tightened slightly (e.g., merging the style enumeration into the flow), but overall it's well-structured and 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?

Given the tool's complexity (10 parameters, no output schema, no annotations), the description is remarkably complete. It covers the tool's role, prerequisites, the primary behavioral caveat, and how to chain it to save_and_present. The only omissions are secondary parameter details, which are minor and do not impair 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 description coverage is 0%, so the description must compensate. It explains key parameters: image_style (user-chosen, eight enumerated styles), image_concepts (plain-words description not company names), banner_text (shortened headline), and banner_kicker (second line). However, slug, description, keywords, entities, and canonical_url are not explained beyond their titles, leaving some parameters under-specified for an agent.

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 'Final step. Everything needed to publish, in one block,' and then lists the exact outputs (title, Blogger labels line, permalink slug, search description, image alt text, gemini_image_prompt). This is a specific verb+resource and clearly distinguishes it from siblings like save_and_present or generate_image by framing it as the assembly step that precedes saving.

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

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

The description gives strong contextual cues: it's the 'final step,' mentions 'the article you just wrote,' and instructs to 'pass the result to save_and_present.' It explains the critical user-choice rule for image_style and the consequence of leaving it empty. It does not explicitly name alternatives or say when not to use it, but the workflow is clear enough to avoid misuse.

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

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

With no annotations, the description carries all behavioral disclosure. It states the tool is 'pure templating, no model call,' describes that it returns validation.issues and instructs agents to 'fix the issues and call again rather than publishing output with a non-empty issues list.' It also discloses the H1 behavior and how to change it with BODY_INCLUDES_H1, which is significant behavioral 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 description is lengthy, but nearly every line adds required detail given the empty schema. It is front-loaded with the purpose, then parameter contracts, then behavioral notes, which is a logical order. It could be tightened with clearer headings, but the density is justified.

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?

The description provides everything an agent needs to call the tool correctly: input contracts, output shape (`paste_block`, `meta`, and `validation.issues`), validation semantics, and pipeline integration with `save_and_present`. Given the lack of output schema and annotations, this is a complete definition.

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 input schema provides no descriptions, but the description enumerates the exact structure expected for `article` (headline, description character count, intro length, section limits, word count, optional fields), the 4-8 entry requirement for `faq`, the public-https requirement for `image.url`, and the source of `keywords`. This richly compensates for the 0% schema coverage.

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

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

The description opens with 'Step 9. Render the HTML body and both JSON-LD blocks, then check them,' which names a specific action and artifact. It goes on to differentiate itself from siblings like write_blog_post and save_and_present by framing it as pure templating and explicitly tying the `meta` output to save_and_present. This makes the tool's role in the pipeline unmistakable.

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 places the tool as Step 9 and does not leave its use to inference: it references the seo_keywords tool for keyword input and directs the `meta` output to save_and_present. However, it never names alternative tools or states explicit conditions under which a different tool should be chosen, so it falls short of full alternative 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?

With no annotations and no output schema, the description carries the full behavioral burden. It discloses the content of the report (provider config plus fallback status) and implies a non-mutating diagnostic, but never states that it has no side effects, whether it requires credentials, or how the result is structured beyond three examples.

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 in the first sentence and the usage trigger immediately after; every clause carries information. The hard line breaks inside sentences are slightly awkward but waste no words.

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

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

For a zero-parameter, output-schema-less diagnostic, the description gives enough to call it confidently and interpret the headline results. It stops short of describing the full shape of the response, which an agent would otherwise have to discover by calling it.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for an empty schema is 4. The description correctly implies the call is unconditional with no required input.

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: reports which providers are configured and which keyless fallbacks are active. It further anchors the purpose by naming three concrete sibling tools whose behavior it explains, so an agent can distinguish it from every other diagnostic in the list.

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

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

Gives an explicit trigger condition ('Call this first when something behaves unexpectedly') and enumerates the specific uncertainties it resolves: verify_news's search key, humanize_text server-side rewriting, and score_ai_text's detector mode. This is exactly the when-to-use guidance an agent needs.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool returns a plan with specific components, and it adds important behavioral rules: every claim must trace to a fact, invented details must not be attributed to sources, and thin sourcing should be marked as background. It does not mention side effects or state changes, but for a drafting/generation tool this is reasonably transparent.

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

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

The description is longer than average but front-loaded with the tool's role and output, followed by essential procedural rules. The imperative instructions are relevant and not filler. A small deduction for slightly repetitive emphasis like 'ACT ON IT IMMEDIATELY' and 'You are the writer' which could be condensed without losing meaning.

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

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

Given the absence of an output schema and annotations, the description does a solid job of explaining what the plan contains continued and how the result should be used ('pass it to build_schema as `article`'). It also covers the downstream quality checks. It is not a 5 because it omits any clarification about the relationship of all input parameters to the returned plan, and the boundary between what draft_brief returns and what the agent writes is slightly ambiguous.

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 for five parameters. It mentions 'facts' and 'keywords' and indirectly references 'FAQ questions', but it does not explain the meaning or expected format of 'headline', 'references', or 'faq_candidates'. The parameter names are self-explanatory to a degree, but the description does not provide enough semantic detail to fully compensate for the total absence of schema 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?

The description states a specific purpose: 'Takes the verified facts and the keywords and returns the plan' and enumerates the plan contents. It also ties the tool to a concrete pipeline position ('Step 5') and names downstream tools like build_schema, which helps distinguish it from siblings. It is slightly less than a 5 because the opening mixes tool purpose with an instruction to 'write the article,' blurring whether draft_brief itself produces the plan or the full article.

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

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

The description gives clear usage context: it is Step 5, and it explicitly instructs the agent to act immediately, not to print the brief for the user, and to run find_ai_words and review_draft before build_schema. This effectively explains when and how to proceed. It does not explicitly name an alternative tool to use instead, but the pipeline ordering provides sufficient 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?

No annotations are provided, so the description carries the full behavioral burden and does well on failure semantics: failed fetches are reported per_url with a reason and never fabricated. It also bounds quote length (<=15 words). Missing: net/HTTP behavior, rate limits, or whether it makes network calls that could be slow/blocked.

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 step and core action, then return shape, then failure handling, then the usage contract. Four short paragraphs, each earning its place. No redundant restatement of the name.

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

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

No output schema exists, so the description must describe returns and it does: facts, quotes, figures, tagged by source_url, plus a per_url failure report. For a two-parameter tool with no annotations, this covers the critical contract. The untouched max_facts_per_url is the main 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% for two parameters (urls, max_facts_per_url), so the description should compensate. It obliquely defines what comes back per URL and the per_url failure structure, which hints at the urls list semantics, but says nothing about max_facts_per_url or batching. Partial compensation only.

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 pair: download verified sources and extract usable material, then names the exact output (facts, quotes, figures). The 'Step 3' marker situates it in a pipeline, but the name alone could be read as purely a fetch operation; the description clarifies the extraction role. It does not differentiate from siblings like verify_news, which produces the 'verified sources' this tool presumably consumes.

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 downstream constraint: everything written must trace back to this output, and out-of-output claims are excluded. This tells the agent when the output is authoritative. However, it never names or excludes sibling tools (verify_news, draft_brief) or states prerequisites for input URLs, so alternative selection remains implicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (clean boolean, count, every occurrence with its sentence) and a comparative cost/precision trait versus score_ai_text. It stops short of stating any auth, rate-limit, or side-effect behavior, but the tool is an analysis read so the gap is minor.

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 in the first sentence, then value-add detail about return values, workflow, and sibling comparison. Every sentence earns its place; the trailing clause is compressed and informative rather than filler.

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

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

No output schema and no annotations, yet the description covers the return payload, the workflow loop, and the stopping criterion. An agent has everything needed to invoke it and act on the result.

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

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

Schema description coverage is 0% for the single required 'text' parameter, so the description must compensate. It implies the input is a draft and gives post-processing instructions about 'every fact, figure, name and link', but never states the format, size limits, or whether text is plain or markdown.

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 draft for stock AI phrasing') plus the output scope ('report exactly where it appears'). It explicitly distinguishes itself from the sibling score_ai_text, so an agent can tell the two apart without opening either schema.

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

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

Gives explicit sequencing ('Run it after humanize_text'), the follow-up action ('rewrite each flagged sentence'), and a stopping condition ('Repeat until clean is true'). It also names the alternative and the condition that selects this tool over score_ai_text.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: searches recent coverage, groups articles, ranks by publisher count and freshness, and mentions specific fields (ready_to_write, age_hours, fetchable_urls). It does not explicitly state read-only nature, rate limits, or pagination, but the described workflow implies a safe read operation. The coverage is strong but not exhaustive.

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

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

The description is well-structured with a clear 'START HERE' opener, examples, and a logical flow from purpose to workflow to parameter guidance. It is somewhat repetitive with two similar topic examples, but each sentence adds value and the key guidance is front-loaded. Slightly verbose but not wasteful.

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 tool with no output schema and zero schema coverage, the description covers purpose, usage, parameter semantics (mostly), and downstream integration. It lacks a description of `limit`, detailed output structure, and error cases, but the provided workflow (ready_to_write, age_hours, fetchable_urls) gives sufficient context for correct invocation. Minor gaps keep it from a 5.

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

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

Schema coverage is 0%, so the description must compensate. It explains `days` (recency window with default 2 and guidance to widen/narrow) and implicitly explains `topic` by contrasting with headlines. However, `limit` is not described at all. While it covers two of three parameters, the missing `limit` leaves a gap for agents unsure of its effect.

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+resource: searches recent coverage, groups articles into stories, and ranks by publisher count and freshness. It clearly distinguishes itself as the starting point for topic-based queries, explicitly contrasting with specific headlines and referencing downstream tools like verify_news and fetch_article_facts.

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 says 'START HERE when the user gives a topic rather than a specific headline,' providing a clear when-to-use condition. It also gives detailed workflow guidance: use ready_to_write stories, check age_hours, pass headline to verify_news and fetchable_urls to fetch_article_facts, and adjust days based on results. This is explicit and actionable.

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

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

With no annotations, the description carries the full burden and does well: it discloses a hidden trademark filter that rewrites brand terms before the prompt leaves the machine, points at the terms_removed field to audit that rewrite, and warns that the returned path is local-only so an unuploaded file leaves NewsArticle.image unreachable by crawlers. It omits cost, latency (image generation is typically slow/paid), and any auth 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?

Three short paragraphs, front-loaded with the action, then the prompt-authoring rule, then the output-handling caveat. Every sentence carries a distinct instruction; 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 3-param tool with no annotations, no output schema, and 0% schema coverage, the description does cover the highest-risk behaviors (prompt content, filter side effect, local-path gotcha). But two of three parameters remain opaque and nothing is said about cost, timeout, or failure modes, so an agent still has to guess on invocation details.

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

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

Schema coverage is 0%, so the description must compensate. It gives real semantic guidance for 'prompt' (build from visual concepts, not brand names), but 'slug' and 'style' go entirely unexplained in both places, including which of banner/square to pick and what slug controls. Partial compensation only.

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

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

States a specific verb and resource ('Generate a banner image for the article') plus the side effect ('save it locally'), and the 'Step 8' framing places it unambiguously in the workflow. No sibling tool could be mistaken for it.

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

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

The step numbering situates it in the pipeline, and the description explicitly routes the agent forward: 'Upload the file and pass a public https URL to build_schema.' It stops short of stating when not to use it or what alternative exists if image generation is undesired.

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

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

With no annotations, the description carries full behavioral burden and does so: it discloses the gating behavior ('every content tool refuses to run until then'), the no-inference policy ('nothing here is inferred from the environment'), and the downstream consequences of the answers (byline, voice, schema publisher, CTA links, canonical URL). This is rich context beyond what a bare read tool would suggest.

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

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

Front-loaded with the imperative 'CALL THIS FIRST' and well-structured into purpose, sequencing, and consequences. Slightly verbose in the detail about answers deciding byline/voice/etc., but every sentence conveys actionable 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 zero-parameter gating tool with no output schema and no annotations, the description is complete: it explains what it checks, what it returns (configured flag and questions), what to do in each branch, and how its results cascade into other tools. No material gap remains.

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

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

Zero parameters, so baseline is 4. The description adds value by explaining that the tool returns a configured boolean and, when false, a set of questions to present to the user, which is meaningful return-shape context even absent a formal output 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 (check) and resource (server setup/profile) with clear scope: whether set up and with what. Distinguishes itself from siblings like set_profile and reset_profile by describing a read/status check, and its 'CALL THIS FIRST' directive makes its role unmistakable.

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 to call this first before anything else, explains the conditional branch (if configured is false, ask returned questions then call set_profile), and states that every content tool refuses to run until then. Alternatives and sequencing are fully specified.

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

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

With no annotations, the description carries the full burden and does: it discloses the two execution modes (server-side vs. mode='delegated_to_caller'), the return fields (rewritten_text, instructions), the caller's obligation to apply instructions preserving facts/figures/names/dates/quotes/URLs, and that voice_sample governs style only. This is unusually complete behavioral disclosure.

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 'Optional' then the core action, and every sentence carries information. The detector-explanation sentence is slightly digressive but justifies the 'prefer review_draft' guidance, so it largely 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?

No output schema and no annotations, yet the description covers modes, return values, constraints on fact preservation, and parameter behavior. An agent has everything needed to call and correctly handle 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 0%, so the description must compensate. It fully explains voice_sample (optional, matches writer rhythm, style only, never contributes facts) with a default-behavior note. The 'text' parameter is only implicitly documented via the delegated-mode reference to text_to_rewrite, so one gap remains.

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

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

States a specific verb+resource ('Rewrite a draft to strip AI writing tells, keeping facts intact') and names the sibling it is not ('Prefer review_draft'). An agent can separate this from review_draft and score_ai_text 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 gives when-not ('Prefer review_draft', 'Use this only to edit text the writer already wrote'), why-not (rewrites produce machine-written prose again), and a disclosure obligation ('tell them it was used'). This is a textbook routing instruction.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the fields that are destroyed (byline, voice) and the resulting state (setup asks again), but says nothing about reversibility, whether other profile data survives, or any confirmation behavior.

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

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

A single, front-loaded sentence with the destructive verb first and the practical consequence second. 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 zero-parameter, no-output-schema tool the description covers the essentials, but with no annotations it leaves key questions open: whether the reset is irreversible, what else is cleared from the profile, and whether prior data can be recovered.

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

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

Zero parameters, so there is no schema semantics to add; the baseline of 4 applies. The description correctly implies the tool takes no arguments.

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 the action ('forget') and the specific state cleared ('the byline and voice'), which distinguishes it clearly from set_profile and get_profile among the siblings. It stops short of saying it resets persisted profile data, but the effect 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?

The stated consequence ('so the setup questions are asked again') implies when an agent would call it, i.e. to force re-onboarding. There is no explicit when-not guidance and no alternative tool named for the adjacent case of merely editing the profile.

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?

No annotations exist, so the description carries the full burden and does so richly: it describes the output structure (must_fix / worth_fixing / consider with sentence-level notes plus positives) and enumerates the concrete checks performed (unsupported figures/quotes, quotes over 15 words, missing attribution, stock AI phrasing, weak openings, hedging stacks, passive density, flat rhythm). This is well beyond what the schema provides.

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

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

Front-loads the purpose and the critical constraint ('Never rewrite it') before elaborating the check list. The final line ('Returning a rewritten draft defeats the purpose') is a mild repetition of the earlier prohibition, costing a little efficiency.

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-annotation, no-output-schema tool, the description covers purpose, inputs, output categories, and the full review rubric. The only shortfall is the unclear handling of the optional `facts` parameter and what happens when it is null.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does by explaining that `draft` is the human-written text and `facts` comes from fetch_article_facts. It does not clarify that `facts` is optional/defaults to null or the expected fact object shape, leaving a gap given the zero 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+resource ('Read the writer's draft and say where it is weak') and immediately distinguishes itself from the sibling humanize_text by forbidding rewriting. The 'Step 6' marker and reference to fetch_article_facts position it precisely in the workflow.

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

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

Clearly says to pass the human-written draft and the facts from fetch_article_facts, and explicitly warns 'Never rewrite it' / 'Returning a rewritten draft defeats the purpose.' It doesn't name an alternative tool to use instead when a rewrite is actually wanted (e.g. humanize_text), but the boundary with the rewrite siblings is strongly implied.

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

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

With no annotations, the description carries the full burden and it discloses a lot: the tool writes a timestamped folder to disk, refuses without `pack`, and returns `SHOW_THIS_TO_THE_USER` and `preview_html` with explicit handling instructions. It is slightly less clear about failure modes beyond refusal and does not state whether existing files are overwritten, but timestamped folder naming implies preservation.

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

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

The description is long but dense and logically ordered: purpose, precondition, return values, file inventory, report contents, then meta guidance. A few statements, such as 'when pack ... is supplied' after already declaring pack required, are redundant, but nearly every sentence contributes useful workflow or behavior 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 12-parameter tool with no annotations and no output schema, the description is unusually thorough about generated files, return values, and workflow dependencies. It is still incomplete because it never defines the required `slug` and `html_body` arguments, and it gives no guidance on how to populate the JSON-LD and presentation-related optional parameters.

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

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

Schema coverage is 0%, so the description must compensate. It does explain `meta` (required keys, origin from build_schema) and `pack` (required source, contents, missing-five warning), and notes that canonical_url and image_url are read from meta when omitted. However, the two required parameters `slug` and `html_body` are never described, and most simple optional parameters such as title, language, image_path, description, json_ld_faq, and json_ld_article receive no explicit semantic explanation.

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

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

The opening line states a concrete action: 'Write the finished package to disk and hand the post over.' It then elaborates with a specific file inventory and the exact user-facing outputs, so an agent can tell this is the final save-and-present step and not a drafting or schema-building tool. It also situates itself as 'Step 11', which separates it from siblings like write_blog_post and build_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 gives an explicit precondition: `pack` from build_publishing_pack is REQUIRED and the tool refuses without it. It names the owning tool, lists what it supplies, and warns that skipping it yields a package missing the permalink, tags, banner URL and image prompt. It also instructs the agent to pass the `meta` dict returned by build_schema, making the call sequence unambiguous.

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

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

No annotations exist, so the description carries the full behavioral burden and does so well: it discloses the dual execution path (real detector API vs local heuristic) and enumerates what the heuristic measures (burstiness, stock phrases, em dash density, lexical variety). It also flags an important interpretive caveat (no score proves authorship).

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

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

Purpose and scale are front-loaded in the first sentence, followed by mechanism and usage notes. The 'Step 7.' prefix is workflow scaffolding rather than tool definition, and the mid-sentence line break adds slight noise, but overall it is tight and earns its 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 one required parameter, no output schema, and no annotations, the description covers everything an agent needs: what it returns (0-100 score), the mechanism and its fallback, the reporting caveat, and the recommended call sequence relative to humanize_text.

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

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

Schema description coverage is 0% for the single 'text' parameter, but the parameter is trivially inferrable from the description's subject ('how human the text reads'). The description adds scale semantics but no input format details, so it partially compensates 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 (score), resource (text), and output scale (0-100, higher = more human), and ties itself to the humanize_text workflow. It does not explicitly distinguish itself from near-siblings like find_ai_words, so it is clear but not fully sibling-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?

Explicit sequencing guidance: check is_real_detector before presenting the number, always surface the authorship caveat, and run before and after humanize_text to show improvement. This tells the agent both when to call it and how to report it, with no inference required.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return structure (score plus must_fix/should_fix/nice_to_have lists), the iterative fix-and-recheck pattern, and the scope ceiling. It does not state side effects (does it persist anything?) or failure behavior, but for a read-only scoring operation those are low-stakes gaps.

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?

Well structured and front-loaded: step context first, then the checklist, then return shape, then the parameter caveat, then the scope boundary. Every block earns its place, though the enumerated check list is somewhat long and could be tightened into a single clause.

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

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

No output schema exists, but the description compensates by describing the score and the three fix-tier lists. No annotations exist, and the description supplies workflow, scope, and the primary return contract. It is complete enough to invoke correctly, missing only side-effect/failure detail that matters little for a scoring 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 0%, so the description must compensate, and it does for the key ambiguity: it explains that `headline` substitutes for a missing H1. It also implicitly ties `primary_keyword` and `meta_title`/`meta_description` to specific checks. However, five of seven parameters (slug, secondary_keywords, and format expectations for html_body/meta fields) receive no added meaning beyond their names.

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

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

The description states a specific verb (Score) and resource (finished body against on-page SEO rules), enumerates the exact checks performed, and explicitly scopes itself: 'On-page structure only - it says nothing about search volume, competition or backlinks.' This cleanly distinguishes it from siblings like seo_keywords and build_schema.

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

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

Provides explicit workflow context ('Step 10... before publishing'), a retry loop ('Fix everything in must_fix and call again'), and a clear exclusion boundary that names what the tool does not cover. The `headline` guidance explains exactly when to pass that parameter versus letting H1 checks fail.

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

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

With no annotations, the description carries the full burden and does well: it names the returned fields, reveals the data source ('real Google autocomplete data'), and discloses a hard limitation ('No search-volume or competition data; that needs a paid keyword API'). It does not cover auth or rate/token behavior, so not a full 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 the step number and purpose, then structured around inputs and outputs. It is longer than average but nearly every sentence adds usable detail; a small amount of the 'Draft the FAQ...' advice borders on downstream workflow guidance rather than tool selection.

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 no annotations, yet the description enumerates the return fields and the tool's limitations, which is exactly the gap it needs to fill. The only real omission is any explanation of the 'include_suggestions' parameter.

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

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

Schema coverage is 0%, so the description must compensate. It usefully clarifies the required 'title' (headline) and the 'texts' array (facts text from fetch_article_facts), but never explains 'include_suggestions', even though that flag governs whether the autocomplete-derived data is returned.

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 ('Mine the keywords this post should target') and places it in a workflow ('Step 4 ... before drafting'). It is clearly distinct from sibling tools like seo_audit and build_schema, which it feeds rather than replaces.

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 sequencing ('before drafting') and precise inputs ('Pass the headline plus the text of the facts returned by fetch_article_facts'), plus the downstream routing to build_schema and seo_audit. There is no explicit when-not-to-use or named alternative, 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?

With no annotations the description carries the full burden, and it does well: it discloses side effects ('Prints as By <name>', drives canonical URLs and CTA links) and defaults (company_url defaults to site_url, logo_url defaults to <company_url>/logo.png). It does not mention permissions, whether it overwrites an existing profile, or what a repeat call does, so there is residual ambiguity.

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

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

Front-loads the purpose sentence, then uses a clean one-block-per-parameter layout that is easy to scan. It is somewhat verbose, but nearly every sentence conveys a behavioral rule or a parameter meaning rather than filler.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers parameter meaning, defaults, enum values and anti-guessing rules. The remaining gap is lifecycle behavior (overwrite semantics, interaction with reset_profile/get_profile), which an agent would still have to infer.

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 fully, and it does: every one of the six parameters gets meaning, plus the tone enum values (neutral | witty | upbeat | heartfelt | sombre) and default chains for company_url and logo_url. This is well above what the bare schema provides.

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

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

The opening line states a specific verb and resource: it records the publisher identity, location and voice. It is clearly distinguishable from siblings like get_profile and reset_profile, which read or clear the same config.

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 timing ('Run once, after asking') and hard constraints on sourcing values (only user-typed, no guesses, no carry-over from earlier posts). It stops short of naming the sibling tools (get_profile, reset_profile) that are the real alternatives, so it is strong but not exhaustive.

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

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

With no annotations, the description carries full burden and does so thoroughly. It discloses the search process, the corroboration threshold (>=2 independent or single primary/official), the meaning of is_legit, aggregator redirects, and how to use fetchable_urls and reference_candidates. This is rich behavioral context beyond the schema.

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

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

The description is long but every sentence carries essential operational guidance. It front-loads the critical 'START HERE' trigger and then systematically covers usage, thresholds, and downstream tool integration. It is structured and efficient, though slightly verbose.

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

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

Given no output schema and no annotations, the description covers the return fields (is_legit, fetchable_urls, reference_candidates), the conditions for each, and how to proceed with the results. It also addresses edge cases (old headlines, aggregator redirects) making it complete for correct invocation and post-processing.

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

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

Schema coverage is 0%, so the description must compensate. It explains days (limits how far back to look) and title implicitly as the headline to verify. However, limit is not explicitly described, though its default and likely purpose (max results) are inferable. It adds value for most parameters but not all.

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 (verify) and resource (a headline), and explicitly distinguishes from find_stories which finds stories for topics. It clearly says this tool confirms a story is real before drafting, so an agent knows exactly what it 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?

It gives explicit when-to-use (user provides a specific headline, even if they only ask for a blog post) and when-not-to (if user gives a topic, call find_stories first). It also explains the days parameter's role and the behavior of old headlines, leaving no ambiguity about invocation.

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

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

With no annotations provided, the description carries the full burden of explaining behavior, and it does so clearly: 'It does not write the article on its own - it checks the input, confirms setup, and returns the ordered plan.' It also tells the agent what happens next: the article is written at draft_brief. This prevents a major false expectation from the tool's name.

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

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

The description is longer than strictly necessary but well structured: purpose first, then use conditions, then behavioral clarification. The repeated emphasis on using it even when the server is not named is slightly redundant but forgivable because it reinforces a key trigger condition.

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 tool with no output schema, the description explains the main return value: an ordered plan with the next call to make. It does not describe the plan's structure or setup requirements, but an agent can correctly invoke the tool and know what to expect next. The key behavioral surprise is fully disclosed.

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

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

The schema has 0% description coverage, so the description needs to compensate. It adds meaning by explaining the parameter is the topic or headline the user asks about, including plain requests like 'write me a blog post about X.' However, it does not describe expected format, length, or how to handle ambiguous topics, so it only partially compensates.

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

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

The opening line states a clear action and resource: 'Write a complete, publication-ready blog post about a news story.' The description then corrects a potential misunderstanding by explaining it does not write the article itself but returns an ordered plan. It does not explicitly distinguish itself from every sibling, but it does point to draft_brief as the step where the actual writing happens.

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

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

The description gives explicit when-to-use guidance: 'USE THIS TOOL whenever the user asks for a blog post, an article, a news write-up, or content about a headline or a current topic.' It also tells the agent what not to do: 'Do not search the web and draft the article yourself.' This is strong, actionable routing guidance.

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