WriteHero: LinkedIn post checker

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds that the tool reports concrete issues to fix rather than editing or publishing, which is useful confirmation that nothing is mutated. It stops short of describing issue severity or ordering.

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 sentence front-loads the use case, then the checklist, then the return value. No filler and no repetition of the title or annotations.

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

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

No output schema exists, and the description compensates by stating the tool returns concrete issues to fix, which is enough for an agent to know it is diagnostic rather than transformative. The shape of the returned issues (list, score fields, severity) remains unspecified.

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

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

There is one required parameter and schema coverage is 100%, with the schema stating "The full post text." The description implies the post text is what gets measured against the 3000-character limit, but adds no format guidance beyond the schema. Baseline 3 applies when the schema does the documenting.

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?

Specific verb (check) plus resource (a LinkedIn post) plus an enumerated list of what is inspected: character count, see-more cutoff, hook score, unrendered Markdown, placeholders, AI-sounding phrases. The pre-publish framing cleanly separates it from siblings that generate or format content.

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?

"Check a LinkedIn post before publishing" gives a clear triggering moment in the workflow. It does not name alternatives such as preview_linkedin_post, so the agent must infer the boundary between validating and previewing rather than being told.

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 meaningful value beyond that by specifying each transformation (Unicode bold/italic, bullet conversion, link flattening, optional em-dash replacement), telling the agent exactly what output to expect.

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 sentence, front-loaded with the core conversion and followed by the enumerated transformations. 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-parameter, no-output-schema transformation tool with full annotation coverage, the description tells the agent everything needed: input format, output characteristics, and the optional 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?

Schema coverage is 100%, so both parameters are already documented, and the description only restates that em dashes are optionally replaced. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb (Convert) and resource (Markdown → LinkedIn-ready text) with a concrete list of transformations. It doesn't explicitly differentiate itself from the close sibling style_linkedin_text, leaving the agent to infer which handles formatting vs styling.

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 'pastes cleanly into LinkedIn,' suggesting it's the step before posting, but there is no explicit when-to-use/when-not guidance and no mention of alternatives like style_linkedin_text or preview_linkedin_post.

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, destructiveHint=false, idempotent, closed-world), and the description adds real constraint context: outputs are capped at LinkedIn's 220-character limit and derived only from the supplied fields. It stops short of saying how many options are produced or in what format.

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 the resource and input constraints front-loaded and no filler. 'Does not change the profile' is slightly redundant with readOnlyHint=true, but it is cheap and reinforces the read-only nature.

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 should characterize the return value; it only guarantees the 220-character limit and is silent on option count, formatting, or variation strategy. For a multi-parameter generator tool, the behavioral picture is adequate but leaves a real 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 100%, so the schema already documents all seven parameters including the goal and tone enums, making 3 the baseline. The description names five of the seven inputs but adds no semantics beyond what the schema states, and omits goal and tone entirely.

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 resource (profile headline options) and the exact inputs they are built from, which separates it from generate_linkedin_hooks and format_linkedin_post. The verb is only implied by the tool name rather than the description text, so it falls short of a perfect 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?

Usage is implied by the resource named (produce headline options from profile inputs) but there is no explicit when-to-use or when-to-prefer-a-sibling guidance. 'Does not change the profile' is a side-effect disclaimer, not a routing rule.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add the genuinely useful trait: missing inputs are left as [brackets] and nothing is invented. That is real behavioral context an agent could not get from structured fields, though it says nothing about how many hooks come back.

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

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

Two short sentences, zero waste. The output shape is front-loaded and the placeholder rule follows immediately as the operative constraint.

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

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

No output schema exists, and the description does cover the return shape at a high level ('opening-line templates') plus the placeholder convention. It stops short of saying how many hooks are produced or their format/length, which is the one thing an agent would still want to know.

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. The description goes slightly beyond the schema by explaining the consequence of leaving optional fields empty — the output keeps bracketed placeholders — which tells the agent that audience and result may be omitted deliberately rather than being required for a good result.

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: it produces opening-line templates (hooks) for a LinkedIn post, parameterized by topic, audience and result. This implicitly separates it from generate_linkedin_headlines, but it never names that sibling explicitly, so differentiation is left to 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 only implied: the agent can infer this belongs at the start of drafting a LinkedIn post. There is no statement of when to prefer it over generate_linkedin_headlines or format_linkedin_post, and no prerequisites or exclusions are given.

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 read-only, idempotent, non-destructive behavior, yet the description adds real context beyond them: the preview is approximate, the link embeds the post text so it is shareable/leaky, and opening the link publishes nothing. That privacy and fidelity nuance is exactly the kind of thing an agent can't get from 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?

Four short sentences, front-loaded with the deliverable, then escalation-relevant details (author fields, no side effects, shareability). Each sentence carries a distinct point, though the sharing caveat and the no-op caveat could be tightened into one.

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 properly explains what comes back (a link) and what it shows. The remaining minor gap is that it doesn't say whether the link is short-lived or what happens if the post text is too long for a URL.

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 all three parameters are already documented in the schema. The description only restates that author_name and author_headline are optional 'when you know them', adding little beyond the schema's own descriptions and max lengths.

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 deliverable (return a link) for a specific resource (preview of a LinkedIn post in mobile/desktop feed, including the 'see more' cutoff). It doesn't explicitly distinguish itself from siblings like check_linkedin_post or format_linkedin_post, so a reader must infer the difference from the word 'preview'.

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

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

Usage is only implied by the framing 'approximate preview' and the advice to pass author fields when known. It never says when to use this instead of check_linkedin_post or format_linkedin_post, and gives no preconditions or exclusions.

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 this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: output survives paste into LinkedIn, and styled letters can be read poorly by screen readers – an important accessibility caveat an agent would otherwise miss. It does not state the return shape, but no output schema exists so a small gap remains.

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 tightly written sentences with zero waste: purpose and output behavior first, the caution second. Nothing is 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?

For a two-parameter, read-only text transform with full schema coverage and annotations, the description covers what the tool produces and the main risk. Minor omissions are that it does not say it returns a plain string or warn about length limits, but nothing an agent needs in order 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?

Schema coverage is 100%, and the enum documents all 14 styles plus a default, so the schema does the heavy lifting. The description's list (bold, italic, bold italic, serif, cursive, strikethrough, underline) only loosely maps to the exact enum values and adds no format-level detail beyond 'short piece of text'. 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 ('Restyle') and resource ('a short piece of text') and explains the effect: Unicode letters that keep their look when pasted into LinkedIn. It names the style families, so its difference from sibling post-level tools is implicit, but it never explicitly contrasts itself with format_linkedin_post or preview_linkedin_post.

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?

'Use sparingly' is real usage guidance, and the LinkedIn-paste context implies when the tool applies. But there is no explicit when-not clause, no mention of the alternative of plain text, and no routing to siblings such as format_linkedin_post for post-level formatting.

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