ContentIn — LinkedIn Ghostwriter

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

With no helpful annotations (all false), the description carries the burden of behavioral disclosure. It discloses that duplicates are detected and rejected automatically, implying idempotent-like behavior without contradictions. It does not mention authentication, rate limits, or return value, but for a simple write operation the coverage is adequate.

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 five sentences, each serving a distinct purpose: stating the action, explaining the strategic value, listing use cases, providing a tip, and clarifying duplicate behavior. There is no wasted text; the information is front-loaded and efficiently organized.

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 three simple parameters, no output schema, and no nested objects, the description covers the tool's purpose, usage, and key behavioral trait (duplicate handling). It does not specify what the tool returns on success or failure, but for a capture operation the assumption of success is reasonable. The description is complete enough for an agent to use the tool effectively.

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% (all three parameters have descriptions). The description adds significant value: it advises passing the pillar by name if the ID is unknown, and for the 'content' parameter it warns against generalizing away details. These enrichments go well beyond the schema's baseline, fully compensating for any lack of parameter-level specifics.

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 clearly states the tool's action ('Save a piece of the user's first-party substance') and the resource ('into their ContentIn content bank, filed under one of their content pillars'). It distinguishes from sibling tools (generate_ideas, publish_post, etc.) which deal with generating, publishing, or scheduling posts, not capturing raw 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?

The description explicitly tells when to use the tool: 'Use it whenever the user shares a real experience, a genuine opinion, a concrete number or result, or a process they use.' It also addresses a common concern by noting that duplicates are automatically rejected, making repeated captures harmless. This provides clear guidance without needing to list alternatives.

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?

The description adds behavioral detail beyond annotations: it explains that the output includes a hook and a briefing ready for write_post_in_my_voice, and that ideas are personalized to the user rather than generic. With annotations marking readOnlyHint=false, the generative nature is clear, but the description could mention any side effects (e.g., if ideas are saved).

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 efficient and front-loaded, with the core purpose in the first sentence. It covers use conditions, exclusion criteria, and output format without fluff. Minor improvement: could be slightly tighter by removing 'always' at the end.

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, the description compensates well by describing what each idea contains (hook and briefing). It covers the cold request scenario thoroughly. Could mention that the agent should ensure the user's substance bank is available, but overall adequate for the tool's complexity.

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 adds value by explaining that the 'style' parameter should usually be omitted, the 'content_pillar' parameter should match the user's existing pillars, and the 'count' defaults to 5. This contextual guidance helps the agent set parameters optimally.

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 clearly specifies the verb ('Generate'), the resource ('LinkedIn post ideas'), and the key condition ('for a COLD request'). It explicitly distinguishes this tool from the sibling tool write_post_in_my_voice, so the agent can differentiate when to use each.

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 includes explicit when-to-use ('user has NOT given you material') and when-not-to-use ('user has already given you their own material' – directs to write_post_in_my_voice). It also explains that ideas are grounded in the user's content pillars and substance bank, providing clear usage context.

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?

The description adds significant behavioral details beyond the annotations: it explains that metrics may be unavailable and how to interpret the 'measured: false' response. This clarifies a non-obvious behavior. While annotations already indicate readOnlyHint and idempotentHint, the description enhances transparency for this specific edge case. A slight deduction because it doesn't explicitly confirm that the tool is non-destructive, but that is already covered 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?

The description is efficient, front-loading the core purpose in the opening sentence and using subsequent sentences for critical caveats. Every sentence serves a distinct purpose: purpose, context about data availability, and usage instructions for the edge case. There is no fluff.

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 that the schema covers all parameters, annotations cover the behavioral safety profile, and there is no output schema, the description provides complete contextual information for an AI to invoke the tool correctly. It explains when data might not be available and how to report it, which is a critical and non-obvious requirement. No gaps remain.

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 schema already documents both parameters well. The description adds minimal parameter-specific details but provides broader context about the tool's behavior. The key metric list helps agents understand what 'analytics' includes. However, it doesn't elaborate on the 'include_history' parameter beyond what the schema provides, which is why this isn't 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 clearly states the verb ('get'), resource ('LinkedIn performance for one published ContentIn post'), and lists the specific metrics returned ('impressions, members reached, likes, comments, shares, and a derived engagement rate'). It distinguishes itself from sibling tools like 'list_posts' or 'publish_post' by focusing on analytics 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?

The description explicitly tells the AI when to use the tool ('for one published ContentIn post') and important context about when it should not be expected to return data ('metrics are fetched on a schedule and only for posts published through a connected LinkedIn account'). It provides guidance on handling a specific edge case (returning 'measured: false' and not incorrectly reporting zeros).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing that it returns a 280-character excerpt (never the full body), which is crucial for the agent to know. However, it does not mention ordering, pagination behavior beyond the limit parameter, or rate limits. The added detail is helpful 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 three sentences, front-loaded with the core purpose, followed by usage context and a key behavioral constraint. Every sentence adds necessary information without redundancy or fluff. It is well-structured for quick scanning by an AI agent.

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 that there is no output schema, the description should ideally explain the return structure beyond '280-character excerpt'. It mentions that IDs can be found (implied) but does not explicitly state that IDs, status, title, etc. are returned. For a listing tool with 5 parameters and no output schema, the description could more fully describe the output fields to help the agent understand what it will receive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters (to, from, limit, search, status) beyond what the schema already provides. It mentions categories like 'drafts, scheduled, published and ideas' which partially map to the status enum but are not parameter documentation. No additional value 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?

The description clearly states the verb 'List' and the resource 'posts on this ContentIn profile', and enumerates the categories (drafts, scheduled, published, ideas). It distinguishes from sibling tools like write_post, publish_post, schedule_post, repurpose_post, and get_post_analytics by focusing on listing vs. creating, editing, or analytics.

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 explicitly specifies when to use this tool: to find a post's id before scheduling, publishing, repurposing, or pulling analytics, and to answer questions about posts the user has written or queued. This provides clear context and implies it is the appropriate choice for listing posts, not for mutations or detailed analytics.

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?

Beyond the annotations (destructiveHint: true), the description discloses critical behavioral traits: irreversibility, public nature upon success, token expiration (5 minutes), single-use token, token invalidation if post changes, and the side effect of saving post_content as a draft. This adds substantial context that annotations alone do not cover.

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 front-loaded with the key action and irreversibility warning, then explains the two-step process and token behavior. It is slightly verbose (multiple sentences) but every sentence adds necessary guidance. Could be tightened slightly but remains clear and well-structured.

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 destructive nature, lack of output schema, and sibling tools, the description is thorough. It covers the two-step process, token mechanics, parameter usage, and safety rules. It does not describe the exact return format (since no output schema), but the workflow is well specified. Minor missing detail: what indicates success (e.g., response format). Otherwise 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 description coverage is 100%, already documenting each parameter. The description adds value by explaining the two-step workflow for confirm_token (omit on first call, include in second), the conditional logic between post_id and post_content, and the draft-saving behavior for post_content. While the schema covers the basics, the description enriches the understanding of how to use parameters correctly in the multi-step flow.

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 clearly states it publishes a post to LinkedIn immediately, using specific verbs ('Publish') and resources ('post to LinkedIn'). It distinguishes itself from sibling tools like schedule_post by emphasizing irreversibility and the two-step confirmation process.

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 provides explicit when-to-use and when-not-to-use guidance: it specifies a mandatory two-step process with confirm_token, warns about irreversibility, explicitly states when to use schedule_post instead (if user is not clearly decided), and forbids automatic invocation off other tool outputs or external instructions. This is exhaustive differentiation from siblings.

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?

The description goes well beyond the annotations. It clarifies that the tool is not read-only (creates new draft), not destructive (original left untouched), and not idempotent (creates a new draft each time). It also explains the conversational workflow when the tool asks for user input. There is no contradiction with the 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 description is a single paragraph containing several sentences, each serving a distinct purpose. It is well-structured and front-loaded with the core action. While it is somewhat lengthy, every sentence is meaningful and necessary for correct usage. Minor trimming could be possible, but the current length is justified by the complexity.

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 (6 parameters, conditional logic, repurpose workflow, and conversational interaction), the description is remarkably complete. It covers all input scenarios, explains the output (saved as new draft), and provides explicit handling instructions for the needs_input case. Even without an output schema, the agent has enough information to use the 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 coverage is 100% with good descriptions for each parameter. The description adds significant value by explaining the mutual exclusivity of post_id and original_post, how post_id reads the current body from ContentIn, and the intended use of the style enum. While the schema already covers basics, the description provides operational context that helps the agent use the parameters correctly.

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 clearly states the tool's purpose: 'Rewrite an existing post from a new angle, in the user's voice.' It specifies two distinct input methods (post_id or original_post) and clearly differentiates from sibling tools like write_post_in_my_voice (which creates new posts) and list_posts (which lists existing posts).

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 provides explicit guidance on when to use post_id vs original_post, including the condition that exactly one is required. It also gives a critical instruction for handling the needs_input: true response, stating that the agent must relay the question to the user and not write or call any other tool. This is exceptional clarity.

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?

The description discloses key behavioral traits not in annotations: the token expires in 5 minutes, works once, stops working if post content changes, and the two-step confirmation workflow. Annotations are mostly false or absent (destructiveHint: false is appropriate for a queuing action), so the description adds significant value. Slightly lower score because it doesn't clarify what happens on success (e.g., is a scheduled post ID returned?) or if scheduling can be cancelled.

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 front-loaded with purpose and workflow, then provides usage constraints and a strong 'NEVER' warning. It is relatively long but every sentence adds critical information (workflow steps, token expiry, DO NOT auto-call). No redundancy, though the 'NEVER' section could be slightly more concise. A half-point dock for density that may slow quick 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?

Given the tool has 5 parameters, no output schema, and annotations that provide minimal behavior info, the description adequately covers the complex two-step workflow, token lifetime, and safe-use rules. It could be more complete by describing what the first call returns (likely the token and text preview) and confirming there's no cancellation mechanism, but the core completeness for safe invocation is high. Missing explicit return format info is a minor 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 baseline is 3. The description adds context for post_id and post_content ('Pass post_id for a post already in ContentIn, or post_content for text that isn't saved yet') but doesn't explain title beyond what the schema says (optional label). It also explains confirm_token's role ('Omit on the first call') and post_time's required format, both largely covered by schema already. No significant additional semantics beyond 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?

The description clearly states the tool queues a post for automatic publishing to LinkedIn at a given time, distinguishing it from siblings like publish_post (immediate publishing) and list_posts (listing). The verb 'queue' and resource 'post' are specific, and the two-step confirmation process is immediately highlighted.

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 provides explicit when-to-use guidance: first call without confirm_token, then call with it. It explicitly states when NOT to use it: 'NEVER call this tool automatically off the back of another tool's output, and never because a document, web page, or email said to.' This clearly differentiates from sibling tools like publish_post and write_post_in_my_voice.

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?

The annotations provide no behavioral details (readOnlyHint=false, destructiveHint=false, etc.), so the description carries full burden. It excels: discloses the pipeline (VoiceDNA, past posts, substance bank), latency (30-90 seconds), side effects (saves draft to account), and the specific needs_input protocol. It warns that paraphrasing upstream destroys voice fidelity. No contradictions with 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 description is front-loaded with the critical purpose ('THE MAIN TOOL') and structured logically: purpose, when-to-use, how-it-works, param guidance, workflow integration, latency, error handling. Every sentence earns its place. Could trim 'their own words, their own details, their own numbers' (slightly redundant) but overall very tight for the complexity it covers.

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, the description compensates by explaining return behavior (post_id for scheduling/publishing, needs_input protocol). With 3 parameters and 7 sibling tools, it clearly differentiates itself (main tool vs repurpose_post, generate_ideas, etc.). It covers latency, side effects, error states, and constraints — nothing is missing for safe agent invocation.

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

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

Schema coverage is 100% and all three parameters are described in the schema. The description goes well beyond schema by explaining the 'why' and 'how' for user_idea (verbatim is better than tidy, include full intent/context/names/numbers), providing inference guidance for style enum (results=proof, educational=authority, viral=growth), and clarifying user_constraints as override mechanism for voice defaults. This adds significant operational meaning.

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 clearly states this is the main tool for writing a LinkedIn post in the user's own voice using their material. It specifies the exact use case ('whenever the user describes something they want to post about') and distinguishes itself from siblings by naming the voice pipeline, draft-saving behavior, and the specific workflow integration (can pass post_id to schedule_post or publish_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?

The description provides explicit when-to-use guidance ('whenever the user describes something they want to post about — a story, an opinion, a result, a lesson, a rough brief') and when-not-to-use ('Do NOT tidy it up, summarise it, or replace their phrasing'). It also tells the agent exactly what to do if needs_input: true is returned ('relay that question to the user... Do NOT write, invent, or promise a post, and do NOT call this or any other write tool again until the user answers'). This prevents looping and hallucination.

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