Skip to main content
Glama

Persuasion Taxonomy

Check and compare headlines, hooks, and subject lines

check_headlines
Read-onlyIdempotent

Check headlines, email subject lines, ad openings, video hooks, social post openings and first lines, and compare options against each other. For each line it tells you whether the line does its job in that spot, meaning which of the nine reader questions it answers, and whether a competitor could send it unchanged. It also shows exactly what a reader sees before the cutoff, flags anything that fails outright, and brings in evidence from thousands of real headline tests. Then it says what each option is betting on and which two to test. It answers requests to check or choose between headlines, hooks or subject lines, including "which one is best?" You won't get a score out of ten. Nobody can predict a winner from the words alone, and that includes this tool.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slot": "<slot>",
      "lines": "<lines>"
    },
    "name": "check_headlines"
  }
}

Input Schema

NameRequiredDescriptionDefault
slotYesWhere the lines will appear: email_subject, ad_opening, landing_page_headline, first_line, video_hook, social_post_open, sales_letter_headline. Each spot has its own job, and the check tells you what it is.
briefNoThe brief. The swap test needs it to tell whether a competitor could send the line unchanged, and without it no line can pass.
linesYes
followsNoWhat the reader saw just before this line, like the ad before a landing page headline, or the headline or subject before a first line.
awareness_levelNoHow much the reader already knows, on Eugene Schwartz's scale: unaware means they don't know they have the problem, problem_aware that they feel it, solution_aware that they know solutions exist, product_aware that they know you, and most_aware that they're ready and only need the offer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / awareness_level / description
      Previous value: -"How much the reader already knows, on Eugene Schwartz's scale. Use unaware if they don't know they have the problem, problem_aware if they feel it, solution_aware if they know solutions exist, product_aware if they know you, and most_aware if they're ready and only need the offer."New value: +"How much the reader already knows, on Eugene Schwartz's scale: unaware means they don't know they have the problem, problem_aware that they feel it, solution_aware that they know solutions exist, product_aware that they know you, and most_aware that they're ready and only need the offer."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial return-shape detail: the nine reader questions, the swap test, a preview of what the reader sees before the cutoff, outright failure flags, evidence from thousands of real tests, and the two recommended test options. It also sets an explicit expectation about a missing capability ("You won't get a score out of ten ... Nobody can predict a winner from the words alone"), which is exactly the kind of limit an agent needs before calling.

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

Conciseness4/5

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

Purpose is front-loaded in the first clause and the sentences are information-dense rather than padded. There is mild redundancy between the opening resource list and the later "check or choose between headlines, hooks or subject lines," and the run of "It ... It also ... Then it says ..." makes it slightly list-like, but nothing is filler.

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

Completeness5/5

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

With five parameters, nested objects, two enums, and no output schema, the description must carry the return-value burden, and it does: it describes the per-line verdict, the swap test, the cutoff preview, failure flags, benchmark evidence, the betting rationale, and the two recommended test options. An agent can predict the response shape and set user expectations before invoking it.

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

Parameters4/5

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

Schema coverage is 80%, so the schema already carries most parameter meaning and the baseline would be 3. The description adds value by explaining the intent behind the structured input: the answers array maps to "which of the nine reader questions it answers," and the brief is tied to the swap test ("whether a competitor could send it unchanged"). It does not clarify slot or awareness_level beyond what the schema enumerations already say.

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

Purpose5/5

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

The opening sentence names a specific verb ("Check ... and compare") plus an enumerated resource set (headlines, email subject lines, ad openings, video hooks, social post openings, first lines). It narrows scope away from general copy work, which separates it from siblings like plan_marketing_copy and diagnose_marketing_copy, and it states a hard boundary ("You won't get a score out of ten").

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

Usage Guidelines4/5

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

It gives a clear invocation trigger: "answers requests to check or choose between headlines, hooks or subject lines, including 'which one is best?'". It also notes the brief is required for the swap test, which is a practical precondition. It never states when to use a different sibling instead (e.g., plan_ab_test or diagnose_marketing_copy), 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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.