VarynForge

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

With no annotations provided, the description carries the full burden and does an excellent job. It reveals that the idea is stored verbatim as provenance, the suggestion is placed into generating_brief, and the brief is forged automatically, plus it warns about free-tier queueing. It even specifies the return value (suggestionId), providing a comprehensive behavioral profile.

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 compact yet information-dense, covering the core action in the first sentence and adding behavioral details in short, purposeful clauses. No wasted words; every phrase adds value relative to the tool's workflow.

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 9 parameters and no output schema, the description provides a strong behavioral overview but fails to explain the input fields or how they relate to the expansion process. It tells what happens on invocation but not enough about how to correctly populate the required arguments, making it incomplete for a complex 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 for the 9 parameters, but it only hints at ideaText as the 'verbatim idea'. It does not explain the meaning, format, or relationships of required fields like angle, searchIntent, or optional fields like nicheFit and relatedQueries, leaving the agent to guess.

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

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

The description opens with a specific verb ('Commit') and clearly defines the object: an expanded idea from expand_idea, committed as a brief-ready article suggestion. It also names the follow-up actions (stores provenance, lands in generating_brief, forges brief), which fully distinguishes it from sibling tools like add_article_suggestion or create_article_suggestion_with_input.

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 in a clear pipeline by stating it takes an expanded idea from expand_idea, implying it should be used after expansion. It also mentions the free-tier daily cap as a conditional, but does not explicitly state alternatives or when not to use it (e.g., for manual article creation).

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 that this creates a 'bare' suggestion with title and optional intent/reasoning, implying it does not produce a full brief (contrasted with the sibling). However, it doesn't mention side effects, permissions, idempotency, or return value, leaving notable gaps for a mutation tool.

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

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

Two sentences, front-loaded with the core purpose, then the alternative. No filler or redundant phrasing. Every word earns its place.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description is minimal. It covers the key distinction from a sibling and the core fields, but lacks information on return value, prerequisites (e.g., content plan must exist), and possible errors. Adequate but not rich.

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 description must compensate. It names three parameters (title, intent, reasoning) and indicates which are optional, but does not explain the meaning of 'intent' or 'reasoning' beyond that. It also omits contentPlanId and projectId, though their UUID format makes them self-explanatory. Partial compensation.

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 function: 'Add a bare article suggestion to a content plan' with a specific verb and resource. It distinguishes from the sibling 'create_article_suggestion_with_input' by explicitly contrasting 'bare' versus 'brief-ready' suggestions, so the agent knows exactly which tool to pick.

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 usage guidance: 'For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.' This clearly tells the agent when to use this simpler tool and when to use the alternative, covering both selection and exclusion.

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 for behavioral disclosure. It only restates the importance parameter behavior ('Marks the competitor as important or ignored on creation') which is already visible in the schema. It does not disclose side effects, error conditions, duplicate handling, authentication requirements, or response 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?

Two concise sentences with no filler. The main action is front-loaded and every word adds value. It is appropriately sized for the tool's simplicity.

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?

Despite being a mutation tool with 3 params, no annotations, and no output schema, the description provides minimal context. It does not explain return values, expected behavior on duplicate domains, or preconditions. For a tool performing a write operation, this leaves significant gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a concrete example for domain and explains the meaning of the importance enum. The projectId is indirectly explained via 'project' in the description, but not explicitly. Overall it adds some semantics beyond raw schema but not comprehensive.

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 action: 'Add a competitor to a project by domain' and mentions the importance marking. It distinguishes itself from list/get tools but does not explicitly contrast with set_competitor_importance, though the 'on creation' phrasing hints at the difference.

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 context is implied: use when adding a new competitor to a project. However, there is no explicit guidance on when not to use it or alternatives like set_competitor_importance for existing competitors. No exclusions or alternative tools are mentioned.

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 reveal meaningful behaviors: naming conventions per type, the 10-destination limit, and the effect on briefs/drafts/lint. However, it omits the 'open' state from the enum, and fails to clarify that name/type are not required by the schema. These omissions make the behavioral contract incomplete, which drops the score from a 4 to a 3.

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 coherent paragraph that front-loads the purpose and then efficiently details states, naming rules, confirmation requirement, and the limit. Every sentence adds value, with no fluff or redundancy. It uses dashes and semicolons to structure complex information without excess length.

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 4 parameters and no output schema, the description covers the essential context: purpose, parameter meaning, usage conditions, and side effects (shaping briefs). The main gaps are the undefined 'open' state and the unaddressed optionality of name/type, which could lead to agent confusion. Overall, it is nearly complete but has these notable omissions.

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 this well for `type` (explaining each enum value in context), `name` (domain for websites, handle with optional @ for social types), and `state` (detected vs planned semantics). It does not explain the 'open' state or that `name`/`type` are optional, but given the richness provided for most parameters, the partial coverage warrants a strong score.

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 action ('Add a destination to a project') and defines the resource ('where the operator publishes'). It distinguishes this add operation from sibling tools like list_destinations, and provides specific detail about destination types and states. This is a specific verb+resource combination with clear scope.

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 clear context for when to use each state ('detected' for existing destinations, 'planned' for intended ones) and instructs the agent to confirm with the operator before adding. It doesn't explicitly name alternative tools, but the usage context is well-defined and excludes non-add scenarios (e.g., removal via web UI). Minor gap: no explicit statement on when not to use the tool beyond the web UI note.

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 discloses key side effects: provenance preservation, duplicate skipping, auto-creating the content plan, auto-forging briefs, free-tier queueing behavior, and the return of suggestionIds. This goes well beyond basic mutation 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?

The description is dense but every sentence contributes critical operational context: purpose, prerequisite calls, side effects, exclusions, and return value. It is front-loaded with the core action and uses parentheticals to avoid verbosity.

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 there is no output schema, the description explicitly states the return value ('Returns the created suggestionIds'). It also covers the full workflow, including the free-tier limitation and a direct instruction not to call a sibling tool, making it complete 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?

Despite zero schema description coverage, the description meaningfully explains how to obtain signalObservationId and topicIndex, and frames angles as coming from expand_radar_topic. ProjectId is inferable from 'content plan,' but topicAngleTotal is never mentioned, leaving one optional parameter semantically undocumented.

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

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

The description opens with a specific verb and resource: 'Add selected angles from a radar topic to the content plan as radar-born article suggestions.' It clarifies provenance and duplicate handling, distinguishing it from related tools like add_article_suggestion and expand_radar_topic.

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 provides explicit sequencing: 'Angles come from expand_radar_topic; call list_radar_topics first to get signalObservationId + topicIndex.' It also gives a clear exclusion: 'do not also call generate_article_brief,' making when-to-use and when-not-to-use 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?

With no annotations, the description carries the transparency burden and does well by disclosing side effects (auto-resolves content plan, creates/links search-query rows), return values (suggestionId + contentPlanId), and the cost/constraint (free-tier, no research run). It does not cover failure modes or permissions, but the key behavioral traits are present.

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, then workflow details, then cost/constraint. Every sentence adds distinct value with no redundancy.

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 (9 parameters, no output schema, no annotations), the description provides a solid high-level workflow and return IDs but fails to explain the numerous parameters and the meaning of 'default content plan'. It is adequate for basic operation but not fully complete for an agent to use 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 description coverage is 0%, so the description must compensate. It provides some meaning for keyword-related parameters (creates/links search-query rows for keywords) but leaves the other six parameters (angle, reasoning, searchIntent, targetAudience, wordCountTarget) unexplained. This is insufficient for a 9-parameter tool.

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 creates an article suggestion from operator input, with specific resource and source. It adds distinct details like 'brief-ready', auto-resolving a default content plan, and returning suggestionId + contentPlanId, which differentiates it from siblings such as add_article_suggestion or generate_article_brief.

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 clear usage context: it is for operator-provided input and is free-tier compatible (no research run required). It implies this is the lightweight path when no research is needed, though it does not explicitly name alternatives or state when not to use it.

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. It discloses key behaviors: auto-creates suggestions, excludes dismissed clusters, excluded terms, and clusters already covered. However, it does not mention side effects, idempotency, permissions, or output/return behavior, leaving some transparency 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?

The description is two sentences with front-loaded main action and well-structured exclusions. Every sentence earns its place, and there is no redundancy or filler.

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

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

For a single-parameter tool with no output schema or annotations, the description is quite complete. It explains the source, the action, the exclusions, and the inclusion threshold. It lacks details on how results are returned or whether an existing plan is replaced, but these are minor given the tool's scope.

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 must compensate. It does not explicitly explain the projectId parameter, but it implies the project must have a completed research run, adding context beyond the schema. The parameter itself is a self-descriptive UUID, so the absence of explicit detail is not a major flaw.

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 creates a content plan by harvesting the top-30 opportunity clusters from a completed research run, and auto-creates article suggestions. It distinguishes from siblings by specifying exclusions and referencing related tools like set_opportunity_status and set_excluded_terms.

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 implies when to use (after a completed research run) and clarifies what is excluded and where those belong (other tools or editorial scores). However, it does not explicitly name alternative tools for creating content plans or state a when-not-to-use condition beyond the 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?

With no annotations, the description carries the full burden and does well: it discloses that the call returns projectId immediately, that niche analysis and asset mapping run async, and that the caller should poll get_project until ready. It also reveals the probing policy for siteRelation, adding useful context beyond the technical operation.

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 concise and front-loaded: 'Create a new project' is the first phrase. It packs essential information into three sentences without redundancy: input alternatives, async behavior, polling instruction, and siteRelation guidance.

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 covers the core flow, async behavior, and immediate return of projectId, which is essential given no output schema and no annotations. However, it leaves several parameters (originType, originInput, originDescription, extras) undocumented and does not explain what the full response contains. It is adequate for basic usage but incomplete for the full parameter set.

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 zero descriptions, and the description partially compensates by explaining website, nicheDescription, and siteRelation. It clarifies that website and nicheDescription are alternatives that can be combined, and it explains the meaning of siteRelation values. However, it does not mention originType, originInput, originDescription, or extras, leaving 4 of 7 parameters without semantics.

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 'Create a new project' with specific input types and return behavior. It distinguishes the tool's resource (project) from sibling tools that operate on other entities like ideas, competitors, or suggestions. The verb+resource combination leaves no ambiguity about the tool's function.

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 guidance on when to use the tool: pass either a website URL or a niche description (or both). It also instructs on handling siteRelation by asking only when ambiguous, never guessing. However, it does not explicitly mention alternatives or when not to use this tool, 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 transparency burden. It discloses a key side effect: deletion cascades to keyword and cluster links, and it mentions the associated brief. This adds context beyond the tool name, though it does not state irreversibility or return 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?

The description is two sentences long, front-loaded with the action, and contains no redundant information. Every phrase adds value, including the cascade note.

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 simple delete tool with one parameter and no output schema, the description covers the main effect and the cascade, which is the most important context. It does not mention irreversibility or success/failure responses, but these are less critical for a delete operation and the description is otherwise sufficient.

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

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

Schema description coverage is 0%, and the description does not clarify the 'id' parameter. While the UUID format is in the schema, the description does not explicitly state that the id refers to the article suggestion id, leaving a small ambiguity. The single parameter is self-explanatory from the tool name, but the description fails to add extra 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 uses the specific verb 'Delete' and identifies the resource ('article suggestion') plus its associated brief, clearly distinguishing it from sibling tools like add_article_suggestion, get_article_suggestion, and update_article_status. The cascade behavior adds further scope clarity.

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?

No explicit guidance on when to use this tool versus alternatives. While deletion is implied, the description does not mention any exclusions (e.g., using update_article_status for status changes instead) or prerequisites. The tool is named clearly, but the usage context is not articulated.

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 discloses key behaviors: returns a single markdown string, capped at ~8K chars, and omits structured fields. It doesn't discuss error conditions or side effects, but for a read-like retrieval tool this is adequate, though 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?

Two sentences: the first identifies the tool's output and use case; the second gives usage parameters and return characteristics. No fluff, and all key information is front-loaded.

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 annotations and no output schema, the description covers the return format, size cap, channel behavior, and the main alternative tool. It doesn't mention prerequisites (e.g., the suggestion must exist) or error handling, but these are not essential for a well-scoped retrieval tool. The description is sufficient for an agent to decide and invoke 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 0%, so the description compensates by explaining format=markdown_inline, channel defaults, and the per-channel brief concept. It doesn't describe suggestionId/projectId, but those are unambiguous from naming and schema types. It also clarifies that markdown_only is the intended format, adding meaning beyond the enum.

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 action—'Get a brief as inline markdown'—and the resource (a brief). It clearly distinguishes from siblings by noting that structured fields are get_article_brief's job, making the purpose 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 explicitly instructs to pass format=markdown_inline and explains the channel parameter's default and role. It also contrasts with get_article_brief, giving a clear alternative when structured data is needed.

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 explicitly states the tool is non-destructive ('without writing anything to the plan') and lists what it returns. It does not disclose potential errors or rate limits, but the critical side-effect-free behavior is clearly communicated.

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 with no wasted words. It front-loads the core action, then summarizes the return values and next-step. Every sentence earns its place, making it highly efficient.

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 simplicity (2 params, no output schema, no annotations), the description is complete. It covers the purpose, non-destructive nature, return fields, and the next step (passing to accept_idea), providing an agent with everything needed to select and invoke 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?

The schema has no descriptions (coverage 0%), so the description must compensate. It indirectly defines the parameters through context ('raw article idea' implies ideaText, 'project's niche' implies projectId), but does not explicitly map each parameter. This partial compensation justifies a score of 3, not lower.

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 uses a specific verb ('score') and resource ('raw article idea against the project's niche'), and clearly distinguishes the tool from siblings by stating it does not write to the plan. This makes its purpose unmistakable and differentiates it from accept_idea, which commits the idea.

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 positions this tool as an evaluation step before committing, stating 'Pass the returned fields to accept_idea to commit the idea.' This names a specific alternative and provides clear context on when to use the tool, fulfilling the when-to-use vs alternatives criterion.

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 transparency burden. It discloses key behaviors: output range (3-6), duplicate detection flagging, optional customPov, and the non-mutating nature (no writes). It could add detail on result shape or error conditions, but the core behavioral traits are well covered.

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, each adding substantive value: purpose, duplicate-flag behavior, optional param, and workflow. No redundant phrases, front-loaded with the core action, and every sentence 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?

Given no output schema and no annotations, the description provides sufficient context for selecting and invoking the tool: it names input source, output shape, duplicate handling, optional param, and the follow-up action. Minor gaps like the exact meaning of 'flagged' are inferable, so it is near-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 0%, so the description must explain params. It explains signalObservationId and topicIndex as inputs from list_radar_topics, and customPov as an optional point of view. It omits projectId, but this is a common context parameter and the other three are well defined. This is strong compensation for low 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 clearly states the tool's function: expand a radar topic into 3-6 candidate article angles, specifying inputs (signalObservationId + topicIndex from list_radar_topics) and output characteristics (title, intent, editorial positioning). It also distinguishes from sibling tools like add_radar_topic by explicitly noting this tool performs no writes.

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 guidance: use list_radar_topics to obtain identifiers, call this tool to generate angles, and pass chosen angles to add_radar_topic. The instruction 'No writes' gives a clear exclusion and directs to the correct sibling for the write step.

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 responsibility and succeeds: it discloses idempotency per channel, derivation from an existing article brief, free vs. quota-consuming behavior, the need for guidance when regenerating, and the entitlement return at cap. This goes well beyond a generic generate action.

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?

Despite being long, the description is dense and well-organized: each sentence adds a distinct behavioral fact (templates, derivation, idempotency, force/guidance, quota). The key action and primary parameter are front-loaded.

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 (five channels, derivation logic, quota, idempotency, output on cap), the description covers all critical invocation details without an output schema. It even specifies the return value when the cap is reached, leaving no major ambiguity.

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 thoroughly explains channel (with per-channel template details), force (regenerate idempotently), and guidance (corrective direction). It does not elaborate on projectId or articleSuggestionId, but their roles are evident from the tool name and requirement context.

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

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

The description opens with a specific verb and resource: 'Forge a writer-ready brief from an article suggestion.' It then explains the channel parameter and how each channel produces a distinct deliverable, clearly distinguishing this generation tool from retrieval siblings like get_article_brief or download_brief_markdown.

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 strong context for when to use the tool: generating a new brief, deriving additional channel briefs, regenerating with force, and supplying guidance. It doesn't explicitly name alternative tools or state 'when not to use,' but the behavioral context 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 the full burden, and it delivers. It discloses the tool's informational nature, explicitly mentions the lint_draft daily verification cap and that it applies on every tier, and signals that this tool is relevant after hitting a rate wall. It also mentions locked paid tools and the upgrade URL, which hints at monetization/auth context. No side effects are claimed, and the read-only nature is strongly implied.

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, information-dense sentence that front-loads the core purpose and then lists the specific fields and usage timing. Every clause adds distinct value: the plan/credits, the lint cap, the next_actions queue, and the 'when to read' guidance. There is no padding or repetition, and the structure is easy to skim.

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 simple status tool with no parameters or output schema, the description provides everything an agent needs: what data is returned, when to call it, and how it relates to the lint_draft workflow (check remaining before a loop). It even tells the agent to use it 'after a wall hit,' which is actionable context. The lack of an output schema is compensated by the explicit field list in the description.

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 has zero parameters, so the baseline is 4. The description adds no parameter details because none exist, but it does explain the significance of some returned fields (e.g., lint_drafts_remaining_today), which gives the agent context for interpreting subsequent tool inputs. This is appropriate for a no-parameter tool.

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 starts with a clear verb+resource pairing ('Get the operator account status') and enumerates the specific contents (plan, credits, quota, lint_draft cap, locked tools, upgrade URL, next_actions). It fully distinguishes itself from sibling getter tools by uniquely covering account-level status and the next_actions queue, leaving no ambiguity about what this tool 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?

The description provides explicit timing guidance: 'Read on session start and after a wall hit.' It also gives a concrete instruction to check lint_drafts_remaining_today before a verification loop, tying this tool into a workflow with lint_draft. This is clear when-to-use guidance, even if it doesn't name alternative tools for exclusion.

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 of behavioral disclosure. It explains the structure of every brief, the difference in article briefs, the effect of compact, and the exact behavior when a brief doesn't exist, including the meanings of 'queued', 'forging', and 'none'. However, it doesn't explicitly state whether calling this tool can trigger forging or is a pure read, leaving slight 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?

The description is multi-sentence but every sentence adds value, covering purpose, channel selection, field contents, compact behavior, and edge-case return states. It is front-loaded with the main purpose and remains organized without fluff. It could be slightly more compact, but the level of detail 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?

Despite no output schema, the description thoroughly explains the returned brief fields, the optional compact behavior, and the precise structure of the missing-brief response including hasBrief, briefStatus, and queuedUntil. This covers both success and edge-case scenarios, making it highly complete 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 description coverage is 0%, so the description must explain parameters. It clearly explains channel's enum values and the default, and what compact=true does. suggestionId is self-evident. This covers the parameter meanings well, though it doesn't add deeper syntax details beyond what the schema already lists.

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 the specific verb-object pair 'Get the full content brief for an article suggestion,' clearly identifying the resource and action. It further distinguishes itself from sibling tools by explaining that a suggestion has one brief per channel, which differentiates from get_article_suggestion or generate_article_brief.

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 clear usage context: you pass a channel to choose which brief, and compact to optionally drop referenceArticles. It also describes what fields always populate, implying when to use the tool. It doesn't explicitly mention alternative tools or when not to use, but the context is sufficiently clear.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It adds valuable status semantics explaining what generating_brief with briefQueuedAt set versus null means, including the automatic forging at reset. This goes beyond the schema and helps the agent interpret the data 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 three sentences, each earning its place: purpose and content list, pointer to alternative tool, and status semantics. It is front-loaded with the primary action and remains compact despite the technical nuance.

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 only one obvious parameter, the description covers the key return elements and the critical status meaning. It does not mention how to obtain the suggestionId (e.g., via list_article_suggestions), but this is a minor gap for a single-entity read 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. It does not explicitly explain the suggestionId parameter, but the parameter name is self-explanatory and its purpose is clear from the tool name. The description adds no additional semantic detail beyond the schema's format and pattern, making it minimally adequate.

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

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

The description opens with a specific verb and resource: 'Get article suggestion details,' then enumerates the included data (metadata, cluster context, brief availability, derived assets, target keywords). It distinguishes itself from the sibling get_article_brief by explicitly saying 'Call get_article_brief for the full brief,' making the purpose and boundary clear.

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 clear context on when to use the tool (to retrieve suggestion details) and directs to get_article_brief for the full brief, which serves as an explicit alternative. However, it does not explicitly contrast with list_article_suggestions or other list tools, so usage guidance is good 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 the burden of behavioral disclosure. It states that the tool returns a URL, describes the changelog content ('plain markdown', 'newest first'), and implies a read-only operation. While it doesn't explicitly mention security/permissions or error cases, the read-only nature is clear from the verb 'get' and the URL return. The description adds context beyond the schema, which is empty.

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 two sentences, with the first sentence front-loading the core purpose and return type, and the second providing actionable usage timing. Every clause earns its place—no redundant or vague wording. Ideal structure for a simple tool.

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

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

For a parameterless tool with no output schema and simple behavior, the description is complete: it tells what the tool returns (URL), the content characteristics (markdown, newest first), and when to use it. There is no missing critical information for an agent to correctly select and invoke this tool among its siblings.

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 has zero parameters, and the description correctly mentions none. The baseline for no parameters is 4, and the description reinforces the simplicity by not inventing any parameters. It adds no extra parameter semantics because there are none to explain, which 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?

Clearly states the tool's function: 'Get the URL of the VarynForge product changelog'. It specifies the resource (changelog), the verb (get), and adds relevant details ('what shipped, newest first, in plain markdown'). This differentiates it from the many other get_* tools in the sibling list, as it uniquely targets the changelog. The mention of 'URL' clarifies the exact return value.

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 when-to-use guidance: 'Fetch it when the operator asks what is new, and in the days after a send_feedback report to check whether the gap they hit has been closed.' This gives concrete triggers for invocation and even ties into the workflow with another sibling tool, send_feedback. No exclusions are stated, but the context is highly specific 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?

No annotations are provided, so the description carries the burden. It explicitly uses 'Get' indicating a read operation and lists the returned data fields, making behavior transparent. However, it does not mention potential errors, authentication requirements, or whether results are paginated, but those are less critical for a simple detail lookup.

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, front-loaded sentence with no filler. Every clause contributes meaning, efficiently covering the action, scope, and return fields.

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

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

With no output schema and no annotations, the description does well to enumerate the expected return fields. For a read-detail tool with only two UUID parameters, this is sufficiently complete. Minor omissions like specific handling of missing entities or pagination do not undermine its utility.

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. The parameter names companyId and projectId are self-descriptive, and the phrase 'in a project context' adds meaning by clarifying that the pair identifies a competitor within a project. Yet it adds no format or relationship details, 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 description clearly states the verb 'Get' and the resource 'competitor company detail in a project context', enumerating the specific data returned (domain, name, importance, top pages, top keywords). This distinguishes it from sibling tools like list_competitors (list all) and set_competitor_importance (mutating).

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 implicitly conveys when to use this tool: when you need a single competitor's detail within a project, given companyId and projectId. It does not explicitly name alternatives or exclusions, but the context is clear from the scope and fields listed.

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 admirably. It discloses the read-only nature ('re-read'), free/uncapped usage, the status-ownership model, forward-only transitions, and per-destination verdicts, plus what each mode returns.

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

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

Dense and front-loaded, with the first sentence defining the core action. Some length is justified by the need to explain the status-ownership model, but it remains focused.

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, yet the description fully covers return values (pipeline status, stored draft, gate receipt with verdict/checks/thresholds), modes, and edge-case behavior. This is complete for a 2-parameter read 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 has 0% description coverage, so the description compensates by explaining format's role (include draft text vs overview). suggestionId is not explicitly described but is clearly implied as the suggestion identifier; the tool's purpose makes it obvious.

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 re-reads an article suggestion's verification state, specifying the exact outputs: pipeline status, stored draft, and gate receipt. It explicitly distinguishes itself from lint_draft, making its purpose 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?

Provides explicit guidance: always use this instead of lint_draft to recover a known verdict. Also explains when to pass format versus omit it, giving clear decision criteria.

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 must carry the burden. It adds context about guide content and timing, but does not explicitly state that this is a read-only retrieval with no side effects. The 'get' verb implies safety, but the description doesn't disclose potential limitations or return 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?

The description is a single sentence, front-loaded with the core purpose, and contains no fluff. Every word earns its place.

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

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

For a zero-parameter tool with no annotations or output schema, the description adequately conveys the guide's scope and recommended usage. It could mention the returned format but that is not essential for such a simple retrieval 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?

The tool has zero parameters, so the baseline is 4. The empty schema fully covers parameters; the description adds nothing needed about parameters.

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 retrieves the VarynForge agent guide and enumerates its contents (workflow paths, token-economy rules, walls/upgrade conventions), distinguishing it from siblings like get_onboarding_guide or get_lint_rubric.

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 instructs 'Read this at session start', providing clear timing context. However, it does not mention alternatives or exclusions, 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 provided, the description carries the full burden of behavioral disclosure. It only describes output content and does not state safety traits like read-only behavior, error handling, or authentication needs. The verb 'get' implies read-only but that is not explicit, and no other behavioral characteristics are disclosed.

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, well-structured sentence that leads with the action ('Get a keyword detail') and provides necessary elaboration without filler. Every word contributes to understanding the tool's purpose, making it highly concise and effective.

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?

Despite having no annotations or output schema, the description gives a solid overview of what the tool returns. However, it omits parameter-level details and behavioral caveats, and given the large set of sibling tools, some guidance on when to use this specific tool would improve completeness. It is adequate but not fully 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?

The input schema has zero description coverage for its two parameters (projectId, queryHash). The description references 'the project' and 'it' for the keyword, providing some contextual hint, but it does not explicitly define either parameter or their formats. It fails to adequately compensate for the missing schema documentation.

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: 'Get a keyword detail' and specifies the exact content returned (pages with positions and ownership, plus related tracked keywords). This distinguishes it from sibling tools like get_competitor_detail or get_opportunity_detail, which target different resources.

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

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

The description implies when to use the tool (when keyword-level ranking data and related keywords are needed) but provides no explicit guidance on alternatives or exclusions. It does not mention list_keywords or other get_* tools, leaving the usage context to inference.

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

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

With no annotations, the description carries the full burden. It conveys that this is a read-only 'get' operation and clarifies the channel parameter's default behavior. However, it does not explicitly mention side effects or error conditions, though none are expected for a getter, so a slight deduction is warranted.

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 appropriately sized and front-loaded with the core purpose. Each sentence provides distinct value: the rubric contents, channel usage, and timing advice. No redundant or filler language.

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 only two parameters and no output schema, the description covers the essential information: what the rubric contains, how to use the channel parameter, and when to call the tool. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the channel parameter in detail (channel's brief, article default, matching lint_draft). SuggestionId is only implied as the article suggestion identifier, but the context makes it clear. This is a solid compensation, though suggestionId could be more explicit.

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 retrieves a verification rubric for an article suggestion, enumerating specific contents (submission format, checks, limits, brief fields). This distinguishes it from sibling tools like lint_draft or get_article_brief, which serve different purposes.

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 guidance is given: fetch before writing, and use the same channel as will be passed to lint_draft. This tells the agent when to use it and how it relates to the linting workflow, making it highly 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?

No annotations are provided, so the description carries the full burden. It discloses return contents (stage, pitch, checklist, next_actions) and a key behavioral rule: 'never run the welcome pitch on an operator whose stage says producing,' which implies diagnostic behavior. However, it does not explicitly state whether the operation is read-only or if any side effects exist, though 'diagnose' suggests non-mutating.

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, each earning its place: purpose, usage triggers and return contents, and a safety rule. It is front-loaded, concise, and free of redundant 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?

Given the tool has no parameters and no output schema, the description fully covers the essentials: purpose, when to invoke, what it returns, and a critical constraint. It is complete for a zero-parameter guidance tool and leaves no obvious gaps.

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

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

The tool has zero parameters, so the schema is empty and there is no parameter semantics to explain. Per the rubric, 0 params receives a baseline of 4. The description adds no parameter-specific meaning because none are applicable.

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+resource: 'Diagnose where the operator is in their VarynForge journey and get a guided setup path.' This clearly distinguishes the tool from siblings like get_account_status and get_instructions by focusing on onboarding progression and setup guidance.

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 when-to-use triggers are provided: 'Call when the operator asks to set up VarynForge, get started, or seems unsure what to do next — and always when list_projects returns empty.' It also gives a clear negative rule ('never run the welcome pitch on an operator whose stage says producing') 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 provided, the description carries full behavioral burden. It thoroughly specifies the output contents (top-20 keywords, top-10 pages, etc.) but does not explicitly state whether the operation is read-only, any permission requirements, or potential side effects. While the output details are useful, behavioral traits like idempotency are assumed rather than disclosed.

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 sentence, front-loaded with the main purpose ('Get a cluster detail'). It lists the specific output components in a structured way with em dashes and semicolons, making it readable. While a bit long, it contains no redundant words and 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?

Without an output schema, the description must explain return values, and it does enumerate the major sections of the response. However, it lacks details on the structure or types of these sections (e.g., whether keywords are objects or strings), and does not mention pagination, error conditions, or how the fields relate to each other. It provides a good overview but not complete context for a developer to fully understand the response.

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

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

Schema description coverage is 0% for two parameters (projectId, clusterId). The description does not explain what these parameters mean or how they relate to the tool's purpose. The phrase 'cluster detail' implies clusterId is the target cluster, but projectId is not mentioned. The description fails to compensate for the schema's lack of parameter documentation.

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 function: 'Get a cluster detail' with a specific list of returned components (keywords, pages, competitors, article suggestions, raw score). It also distinguishes itself from sibling tool list_opportunities by contrasting the raw OpportunityScore with the normalized version.

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 context for when to use this tool: when you need a cluster's detailed breakdown. It explicitly references list_opportunities as an alternative for the normalized score, providing partial alternative guidance. However, it doesn't offer explicit exclusions about when not to use it compared to other detail tools like get_competitor_detail.

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 an important behavioral trait: 'headingOutline', 'targetKeywords', and 'contentAnalysis' populate only for owned (asset-mapped) pages. However, it does not clarify what happens for non-owned pages (empty fields, omitted fields, or error), and it omits other behavior like error cases or response shape.

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

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

Two sentences, front-loaded with the core purpose, and every clause adds meaningful information. No filler or redundant phrasing.

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 lists the primary content of a page dossier and notes the conditional population of certain fields, which is useful. However, it lacks context about the meaning of 'owned' pages, the structure of the response (no output schema), and any edge cases or prerequisites. It is minimally viable but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It fails to explain pageId and projectId beyond their names, which are self-descriptive but still lack explicit semantics such as how they relate or how to obtain them. The description adds no value over the raw 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 states a specific verb ('Get') and resource ('page dossier') and lists the included fields (URL, title, project rankings, ownership). It is clear and not a tautology, but it does not explicitly differentiate from sibling tools like get_project or get_project_overview, so it stops short of a 5.

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?

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives (e.g., list_pages or get_project), nor does it state any exclusions or prerequisites. The context signal of sibling tools is not leveraged in the description.

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 richly: GAPS ONLY, volumeBucket buckets with no search-volume numbers, coveredOpportunities never pitched as new work, covered clusters never in the sequence, branding slot, operator's own template, and the {runStatus, report: null} return for incomplete runs. This goes far beyond the tool name and 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 front-loaded with the core purpose, but the rest is one long, dense paragraph with multiple nested parentheticals. It contains a lot of necessary detail for a complex tool with no annotations, but it would benefit from clearer structure (e.g., bullets) to improve scannability.

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

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

For a complex tool with no annotations and no output schema, the description is unusually complete: it covers the full payload structure, design constraints, render instructions, cost implications, runId provenance, and the incomplete-run return behavior. An agent has enough context to invoke it correctly and interpret the result.

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

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

There is only one parameter, runId, and the schema only defines it as a required string. The description adds meaning by specifying the source ('Pass the runId from get_research_status') and the completed-run requirement, which is valuable context 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 states a specific action ('Assemble the client-ready pitch report payload') tied to a precise resource ('a completed research run'), and then enumerates the payload's components (niche profile, competitor landscape, opportunity map, 90-day sequence). This clearly distinguishes it from sibling tools like get_starting_point_report or get_research_status.

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: only for a completed research run, pass runId from get_research_status, and non-completed runs return a null report. It doesn't explicitly name alternative tools or call out when not to use it, but the precondition and runId source are 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?

With no annotations, the description must carry the burden. The verb 'Get' implies a read-only operation, and the description discloses the returned fields. However, it does not explicitly state non-mutating behavior, error conditions, or any other behavioral nuances.

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, front-loaded sentence with no superfluous words. It efficiently communicates the tool's purpose and output contents.

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 simple one-parameter getter, the description is adequate but not fully complete. It identifies the returned attributes but omits any distinction from similar sibling tools and does not describe return format or potential limitations. Without annotations or an output schema, a bit more context would be valuable.

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

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

Schema description coverage is 0% and the description adds no meaning to the 'projectId' parameter beyond its name and schema format. The parameter is self-explanatory from its name, but the description does not compensate for the lack 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 clearly states the verb 'Get' and the resource 'one project', then specifies exactly what is included: niche profile, target audience, and current research status. This distinguishes it from sibling tools like list_projects (which lists many) and provides concrete content expectations.

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?

No guidance is given on when to use this tool versus alternatives such as get_project_overview or get_research_status. It implies usage for single-project details but does not state exclusions or contrast with similar getters.

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 present, so the description carries the burden. It clearly implies a read-only operation via 'Get' and explicitly lists the returned fields. It does not mention error handling, but for a simple retrieval, this is adequately 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?

A single sentence with no wasted words. The verb and resource are front-loaded, and the field list adds clarity without verbosity.

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 tool is simple (one parameter, no output schema), and the description lists the key return fields. It does not explain return format or error cases, but those are less critical for a straightforward getter with a well-specified schema.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly refers to projectId by saying 'associated with a project', but does not explicitly explain the parameter's meaning or format. Given the single obvious parameter, this is acceptable but not highly informative.

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 uses a specific verb ('Get') and names the exact resource ('asset') with clarification ('website/product') and lists the fields returned (URL, name, description, solution profile). This clearly differentiates it from siblings like get_project or get_project_overview.

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?

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without mentioning any differences from sibling tools like get_project or get_project_overview, nor any conditions or prerequisites.

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 full burden for behavioral disclosure. It thoroughly explains how nextActions and topPriorities are ranked, how to interpret 'do the next piece' based on statuses, and why scores/clusters may be null. This is detailed and transparent beyond a simple 'get' read.

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 adds value—explaining ranking logic, status filters, and interpretation rules. It is front-loaded with the main purpose and then provides necessary operational detail. Slightly dense 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?

Without an output schema, the description must explain return values, and it does comprehensively. It details the structure of nextActions and topPriorities, including ordering, scoring, and status semantics, making it complete 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?

The description provides zero information about the single projectId parameter. Since schema coverage is 0%, the description should compensate, but it doesn't. The parameter name and schema make it obvious, but the description adds no meaning beyond structured data.

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 function: to get an at-a-glance overview of a project, listing specific components (niche summary, keyword stats, nextActions, topPriorities). This distinguishes it from siblings like get_project by emphasizing it's an overview, not full details.

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 phrase 'at-a-glance read' implies when to use it (quick overview), but it does not explicitly compare to alternatives like get_project or mention when not to use it. No exclusions are given, so usage is implied rather than explicit.

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 adds useful behavioral context: it explicitly states the tool is 'token-light' and returns a 'small fixed shape, no step payloads.' This discloses the output's size/performance traits beyond what a simple 'get' would imply.

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 efficient sentences. The first sentence front-loads the action and outputs; the second adds a token-usage caveat. No wasted 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?

The tool has a single parameter and no output schema, so the description's enumeration of returned fields (runId, status, progress, elapsed, last error) provides a reasonably complete picture. It omits details like status value enumerations, but for a simple polling tool this is adequate.

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

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

Schema description coverage is 0%, and the description does not explain the projectId parameter beyond saying 'for a project.' It does not mention how to obtain the projectId or its meaning, leaving the agent to rely solely on the schema's UUID format.

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

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

The description clearly states the tool polls the latest research run for a project and lists the specific fields returned (runId, status, progress percent, elapsed seconds, last error). This distinguishes it from sibling tools like start_research_run which would initiate a run.

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 verb 'poll' implies repeated checks after starting a research run, providing clear context. However, it does not explicitly mention when not to use it or contrast with the start_research_run sibling, though the sibling names make the distinction inferable.

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 what data the report contains, that it is free, the difference between markdown and structured fields, and that lockedSections are absent. However, it does not explicitly state potential error conditions or whether the tool can be called on a project with a completed run (though it implies preference for another tool). Slight gap but overall strong.

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 and front-loaded with the primary purpose. Every sentence provides valuable context—content, pricing, rendering options, lockedSections, and alternative tool—without redundant wording. It is appropriately sized for 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?

The description fully contextualizes the tool within its ecosystem: it clarifies the report's scope, availability, relationship to research runs, and the preferred alternative. With only one parameter and no output schema, this description is complete enough for an agent to invoke 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?

The schema description coverage is 0%, so the description must compensate, but it never explicitly mentions the 'projectId' parameter or its semantics. It only says 'for a project', which is vague. The parameter name is self-explanatory, but the description adds no additional meaning beyond what the schema's name itself conveys.

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 gets a 'free starting-point report for a project' and enumerates its content (positioning, content inventory, competitor set, rising-topic signals). It also distinguishes it from the sibling tool get_pitch_report_payload, fulfilling the differentiation requirement.

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 guidance is provided: 'Free on every plan, no research run required' and 'Once the project has a completed run, prefer get_pitch_report_payload'. This tells the agent exactly when to use this tool and when to use the alternative, making the usage context unmistakable.

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. It discloses key behavioral traits: the payload is intentionally compact with FAQ caps and section degradation, and deepLinks is null over MCP (existing only for web users). This goes beyond a simple 'returns data' statement, though it doesn't mention error behavior or permissions, which are less critical for a read-only fetch.

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 information-dense yet concise. It opens with the core purpose, then explains compactness, names alternatives, and notes the deepLinks behavior. Every sentence contributes value with no fluff or repetition, achieving a balance of completeness and brevity.

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 simple get-by-ID tool with one parameter and no output schema, the description is remarkably complete. It specifies what is returned, what is not, and where to get the missing pieces. The deepLinks caveat adds necessary MCP-specific context. No significant gaps remain for an agent to invoke it correctly.

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

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

The schema has one param (suggestionId) with 0% description coverage, so the description must compensate. It does by linking the parameter to 'an article suggestion,' making it clear the ID refers to that entity. The param's name and format (UUID) provide additional obvious meaning, so the description adds sufficient context without needing extra syntax details.

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 'returns a compact writing payload for an article suggestion' and lists its contents (brief essentials, keywords, acceptance criteria, lint instructions). It distinguishes itself from siblings by emphasizing 'Compact by design' and directing users to get_article_brief and get_lint_rubric for the full versions, making its specific role 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 description explicitly says when to use this tool ('One-call writer handoff') and explicitly points to alternatives for fuller data: 'the FULL brief is get_article_brief and the full check list is get_lint_rubric, so verify against those, not this.' It also clarifies the deepLinks limitation over MCP, giving clear context for when this behavior matters.

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. It discloses that each channel has its own methodology and lists the content areas covered, providing useful behavioral context beyond the tool name. It does not mention side effects (none expected) or return format, but for a read-only retrieval tool, this is sufficient.

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 concise and front-loaded with the main purpose, then expands on channel specifics in a structured list. Every sentence adds value, with no redundancy or 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 simple tool with one parameter and no output schema, the description is complete. It tells the agent what the tool does, how to choose the channel, and the default behavior. No critical information is missing.

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

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

The schema provides no description for the channel parameter (0% coverage), but the description compensates fully by explaining each enum value in detail: article, x, linkedin, reels, youtube, including the default. This is exactly the kind of semantic enrichment needed.

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 function: 'Get the writer system prompt for drafting one content type from its brief.' It also details the specific resource (system prompt) and the channel parameter, making it distinct from sibling tools like get_instructions or get_lint_rubric.

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 usage guidance: 'Load the prompt for the channel you are about to draft; article is the default.' It also explains what each channel covers, helping the agent choose correctly. It does not name alternatives or when-not-to-use, but the context is clear.

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

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

With no annotations, the description fully discloses side effects: pass/flag transitions, forward-only status guarantees, storage per format with replacement semantics, daily caps, cache behavior, waiveChecks mechanics (checks still run and are recorded), and the fact that published URL is recorded later. It even describes per-channel submission shapes (e.g., no links in x/linkedin bodies).

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 dense paragraph covering many edge cases. Every sentence adds value, but it would benefit from bullet points or section breaks for readability. It is concise in the sense of no fluff, but structure limits scannability.

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

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

Given no output schema, the description explains return fields (verdict, per-check detail, status, nextAction, thresholds), behavior, parameter semantics, side effects, and cross-tool references. It is complete for a complex mutation/verification tool with 5 parameters and advanced features like waiveChecks and cache.

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

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

Schema description coverage is 0%, so the description carries full burden. It explains channel enum ('declares WHICH of the suggestion's per-channel briefs...'), format ('labels the storage destination' and replacement rule), draft (shape per channel), and waiveChecks (operator-only, still run, don't fail verdict). Even suggestionId's role is implied via 're-submitting the same format replaces that destination's draft.'

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

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

The description opens with a specific verb+resource: 'Submit a draft for verification against its brief. Returns a pass/flag verdict with per-check detail.' It clearly distinguishes itself from siblings like get_lint_rubric (rubric spec) and get_draft_status (re-reading stored verdicts) by describing verdict transitions and storage behavior.

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 alternative tools: 'Verdicts and drafts are stored per format and re-readable any time via get_draft_status (free — never re-lint to recover a lost verdict)' and points to get_lint_rubric for channel limits and list_destinations for format ids. It also states when waiveChecks should be used (only operator), and that unchanged re-submissions are cached.

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 burden and does so thoroughly. It details status semantics (e.g., generating_brief with briefQueuedAt set means queued behind a cap and forges automatically; null means actively forging and to re-check within a minute), plus reveals the structure of the distributions rollup. This is rich 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 long but every sentence earns its place. It front-loads the core purpose and fields, then provides usage guidance and detailed status semantics in a structured, scannable way. No redundancy or 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?

Given the lack of output schema and annotations, the description is remarkably complete: it lists return fields, explains the distributions structure, gives usage guidance, and covers important status behavior. The only notable gap is the under-explained input parameters, which prevents a perfect score.

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, but it does not explain the parameters (projectId, limit, cursor, status). It mentions 'for a project' and 'page through' but does not clarify parameter names, formats, or how status filtering works. The status semantics apply to returned data, not to the status parameter.

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 lists article suggestions for a project and enumerates the returned fields (title, status, priority, etc.). It distinguishes itself from the sibling get_article_suggestion by noting that for full records one should call that tool.

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 advises using the distributions rollup to spot gaps without per-item reads, and instructs to page through suggestions while calling get_article_suggestion for full records. This gives clear when-to-use guidance relative to 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?

With no annotations, the description carries the full burden. It discloses sorting order (important → default → unmarked → ignored, then by domain) and the 100-item cap, which are behaviors not inferable from the schema. It does not detail return fields or pagination, but the disclosed behaviors are sufficient for a read-only list operation.

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 two sentences, front-loaded with the verb 'List' and the resource 'companies'. Every clause adds value: the categories, sorting order, filter option, and cap. There is no fluff or repetition.

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

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

For a tool with no annotations and no output schema, the description covers purpose, sorting, filtering, and result cap. It does not describe the return structure, but given the tool's simple list nature and the explicit mention of company categories, it is reasonably complete. A slight gap is the lack of fields returned per company, which would aid agent expectations.

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 explicitly explains the 'importance' parameter as a bucket filter and the 'limit' cap (capped at 100), adding meaning beyond the schema. 'projectId' is implied via 'for a project', though not explicitly described, the lack of detail is acceptable given the UUID format in 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 tool lists companies for a project, distinguishing marked competitors (important, default, ignored) from unmarked SERP-discovered ones. It specifies the sorting order and filtering option, which uniquely identifies this as a list operation compared to sibling tools like add_competitor_by_domain or get_competitor_detail.

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

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

The description implies usage context by mentioning the optional 'importance' filter and the project scope, making it clear when to use this tool for listing competitors. It does not explicitly contrast with alternatives, but the naming and context provide sufficient guidance for typical list scenarios.

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 full burden. It discloses field semantics (briefChannel, verifiable, publishable, publishVia), explains null values, and links publishVia to specific recording tools. The empty-list behavior is also described, giving a complete picture of the tool's operational traits.

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?

While lengthy, every sentence serves a purpose: listing destination examples, explaining field meanings, and describing empty-list handling. It is well-structured and front-loaded with the main action, with no redundant or fluff content.

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 is thorough for a list tool with a single parameter and no output schema. It covers what destinations are, what each field represents, why those fields matter, and what to do if the list is empty. It leaves no significant gaps in operational understanding.

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 for projectId. It only says 'the project's destinations', which implies projectId identifies a project but does not explain how to obtain it or its format. The schema's type/format already provides the syntax, and the description adds no extra semantic value.

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: 'List the project's destinations'. It defines what destinations are, lists the known types, and distinguishes itself from sibling list tools by focusing on destinations specifically.

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 provides explicit guidance on when to use this tool and what to do with the results: 'An empty list means... add one with add_destination, or fall back...'. It also explains that the data is self-contained so you never cross-reference other tools, which is strong 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?

With no annotations provided, the description carries the full behavioral burden. It discloses key behaviors: pagination, sorting support, and an intent filter, plus the volume bucket enum values. This gives the agent a solid sense of what to expect, though it doesn't mention error cases or data modification (but 'list' implies read-only).

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 one efficient sentence, front-loaded with the primary action and resource. Every phrase adds value: tracked project, returned fields, pagination, sorting, and filtering. No redundant words or 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?

The tool is moderately complex with 5 params including nested objects and no output schema. The description covers the high-level behavior and return fields but omits details like cursor semantics, default limit behavior, error handling, and output format structure. This leaves reasonable gaps for an agent to fully understand the tool's 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 description coverage is 0%, so the description must compensate. It only mentions 'sorting' and 'intent filter' generically, without explaining parameters like limit, cursor, projectId, or the structure of filters/sorting. The fields listed (text, difficulty, intent, volume bucket) refer to return values, not input parameters, leaving parameter semantics largely unexplained.

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 lists keywords for a project, specifying the resource (keywords) and scope (tracked for a project). It also enumerates what is returned (text, difficulty, intent, volume bucket), distinguishing it from sibling list tools like list_competitors or list_pages.

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

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

The description implies usage when you need to list keywords for a project and mentions supported capabilities (pagination, sorting, intent filter). However, it does not explicitly contrast with alternative list tools or state when not to use this tool, which limits 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 provided, the description carries full burden and excels: it discloses defaults, hidden clusters, down-weighting of excluded terms, and normalization of scores. It also notes that filtering changes relative scores, which is a non-obvious behavioral trait.

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 dense but every sentence contributes: it starts with the core purpose, then details filters, followed by exclusions and score normalization. No filler or redundant 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?

The description covers the tool's main behavior and filtering nuances thoroughly, given there is no output schema. It lacks an explicit description of the return object shape or pagination behavior, but the detail provided is substantial for a list operation.

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

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

Schema description coverage is 0%, and the description compensates strongly for 'goal' and 'coverage' by explaining their enum values and semantics. However, it does not elaborate on limit, cursor, activeMetaCluster, excludeInContentPlan, or projectId, leaving some params underspecified.

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 lists content opportunity clusters sorted by opportunity score, with specific filter parameters. It distinguishes from sibling tools like get_opportunity_detail by focusing on the list operation and explaining scope.

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 clear context on when to use the tool, including default coverage behavior and the impact of dismissed/excluded clusters. However, it does not explicitly mention alternative tools or when not to use it, such as pointing to get_opportunity_detail for single-cluster details.

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 must carry the transparency burden. It discloses the return fields and filter capabilities, and implies a read-only operation via 'list.' However, it does not mention pagination (cursor/limit), sorting behavior, or any potential side effects, leaving some behavioral aspects undisclosed.

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 extremely concise, consisting of two sentences. The first sentence front-loads the purpose and key return fields, while the second adds filter information. Every word earns its place, and there is 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?

Although there is no output schema, the description lists the main return fields and filtering options. However, the tool includes a nested filters object, a sorting array, and pagination parameters that are not addressed. This leaves contextual gaps for an agent trying 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 description coverage is 0%, so the description must compensate. It only explains filtering by ownership and company domain, which maps to the filters object, but it does not explain limit, cursor, or sorting parameters. These are left entirely to the agent's interpretation of parameter names, which is insufficient for a nested 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 a specific action and resource: 'List ranked pages tracked for a project.' It also lists return fields (URL, title, company, query count, ownership), which clarifies what the tool provides. This distinguishes it from sibling list tools like list_keywords or list_projects.

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 context: it is for listing pages tracked for a project, with optional filtering by ownership or company domain. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select this tool for page listing.

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 burden. It discloses pagination, sortable fields, and defines lastActivityAt semantics, which is useful. But it omits details like response format, error behavior, or rate limits, so it doesn't fully compensate for missing 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?

Two sentences, each earning its place. The first sentence captures the core function and key capabilities; the second adds a practical definition and heuristic. No redundant 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 list tool with moderate complexity and no output schema, the description covers purpose, pagination, sorting, and a disambiguation rule. Missing response format and cursor details, but these are not essential for basic use. Overall, it's sufficient for an agent to understand when and how to call it.

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

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

Schema coverage is 0%, so the description must compensate. It mentions pagination (limit/cursor) and sorting by createdAt, niche, or industry, which maps to the sorting array. However, it doesn't explain cursor mechanics, limit defaults, or how to specify desc order in the sorting array, leaving gaps for parameter usage.

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 lists all projects for the authenticated operator, with a specific verb ('List'), resource ('projects'), and scope. It also distinguishes from siblings like get_project by specifying it lists all projects, not a single one.

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 clear context: use when you need all projects, with pagination and sorting options. It also gives a decision heuristic for picking a project from 'my project' references (highest lastActivityAt), which guides usage. However, it doesn't explicitly mention alternatives like get_project for individual retrieval.

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 burden. It discloses the null-return behavior when no snapshot exists and outlines the return contents. However, it does not explicitly state that the operation is read-only or mention any side effects, despite being safe to infer from the verb 'List'.

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: the first states the purpose and contents, the second handles the empty case, and the third points to a related tool. Every sentence earns its place, is front-loaded, and contains 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 the simple list operation with one parameter and no output schema, the description is largely complete: it explains the returned fields, the null case, and a follow-up action. It lacks only minor details like ordering or pagination, which are not critical for a snapshot 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 should compensate. It does not explicitly describe projectId, but the phrase 'for a project' adds context that the string parameter identifies the target project. For a single obvious parameter, this is marginal compensation.

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 lists the latest emergent-topic radar snapshot for a project, with specific content fields (label, summary, momentum, novelty, drivers, evidence) and per-topic index/article suggestion counts. The verb 'List' and resource 'radar snapshot' distinguish it from siblings like expand_radar_topic and add_radar_topic.

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 guidance to use expand_radar_topic for converting topics into angles, and notes the null return when no snapshot exists. It does not explicitly state when to use this tool over other list tools, but the context is clear enough.

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 responsibility. It discloses immediate IndexNow ping, the consequence of pinging a dead URL ('search engines crawl, hit the 404, drop it; nothing re-pings later'), and the behavior on an already-published suggestion. It also clarifies the publishedAt constraint and the fact that the call records the real go-live moment.

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 each sentence adds critical information about timing, side effects, or alternatives. It is front-loaded with the main purpose in the first sentence. While it could be trimmed slightly, every sentence earns its place in covering the tool's 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 (multiple side effects, timing constraints, edge cases) and no output schema or annotations, the description is remarkably complete. It covers the main action, prerequisites, alternative workflows, parameter specifics, and an edge case (attaching a URL to an already-published article), leaving no significant 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%, so the description must compensate. It thoroughly explains publishedAt: 'Pass `publishedAt` (ISO datetime, must not be in the future) when the article went live EARLIER than this call' with examples. It does not explicitly describe id or publishedUrl, but these are self-evident from context and tool name, so the added semantics for the ambiguous parameter merit a high score.

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: 'Record that an article went live at a URL. Flips the suggestion to published, writes the distribution ledger row, stamps the Passport, and pings IndexNow.' It enumerates specific side effects and distinguishes itself from update_article_status with 'Use this instead of update_article_status for the published transition.'

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 usage guidance: 'Call it only once the URL actually resolves' and contrasts with update_article_status, noting 'a status flip alone records no URL'. It also explains the CMS-scheduled alternative flow using update_article_status and ready_to_publish, giving clear when-to-use and when-not-to-use 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 provided, the description carries the full burden, and it delivers rich detail: 'every registration is kept,' 'never affect publish status or Search Console attribution,' and 'VarynForge never posts on your behalf.' These behaviors go beyond the schema and are critical for correct use.

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 primary purpose, then incrementally adds important nuances. Each sentence earns its place: purpose, effect on reporting, channel behavior, scheduledFor caveat, and non-interference with publish status. Despite its length, it is tightly written and information-dense.

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 5 parameters, 3 required, no annotations, and no output schema, the description is remarkably complete. It covers all parameters, side effects, boundaries, and alternatives. The agent can safely invoke the tool without additional guessing.

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 explain parameters, and it does thoroughly. It explicitly describes `channel` (with enum values), `scheduledFor` (display-only date), and `url` (new URL for repeat posts). It also implies `suggestionId` ('produced from an article suggestion') and `kind` (the list of asset types). It adds semantics beyond the bare 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 opens with a specific verb and resource: 'Register a derived asset... produced from an article suggestion.' It clearly identifies the input (suggestionId, kind, url) and the output (distribution-ledger row, derivedAssets in get_article_suggestion). It distinguishes from siblings by explicitly naming mark_article_published as the tool for the article itself.

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 context: when to register derivatives produced from article suggestions, including repeat posts on the same channel. It gives an explicit alternative: 'use mark_article_published for the article itself.' It also clarifies that scheduledFor is display-only and VarynForge never posts, setting appropriate expectations.

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 discloses important behavioral traits: it re-crawls (a mutating action), is rate-limited per site, and returns a wait-time error during cooldown. This goes beyond a simple 'refresh' statement and gives the agent actionable expectations, though it doesn't detail success response or 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?

The description is three sentences with no filler: action, usage trigger, and rate-limit behavior. Every sentence earns its place and information is front-loaded with the core action.

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

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

For a single-parameter tool with no output schema, the description covers the action, when to use it, and a key constraint (rate limit). It lacks an explicit statement of what a successful call returns or whether the operation is asynchronous, which prevents a perfect score.

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 zero description coverage for the only parameter (projectId), so the description must compensate. It refers indirectly to 'the project website' but never explicitly states that projectId identifies the project to remap. The parameter name and schema format are self-explanatory, but the description adds minimal semantic detail.

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 action ('Re-crawl the project website') and resource ('owned pages'), clearly distinguishing this tool from read-only siblings like get_project_asset and list_pages. It also ties to a concrete trigger (mappingStatus error or stale pages), making the purpose 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 description gives an explicit when-to-use condition: 'Use when get_project_asset shows mappingStatus "error" or owned pages look stale.' This is clear context, but it does not explicitly state when not to use or mention alternatives, 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 fully discloses the tool's behavior: there is no reply, feedback is never a ticket, and one must check get_changelog later. It even states that entitlement-wall payloads are working as designed, which helps the agent calibrate what to submit.

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?

Five sentences, each earning its place: purpose, when to call, exclusions, the non-ticket caveat, and the follow-up expectation. Front-loaded with the verb 'File' and no wasted 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 simple fire-and-forget feedback tool with no output schema, the description covers all necessary aspects: purpose, triggers, exclusions, expectations, and follow-up. It is fully self-contained and leaves no critical ambiguity for an agent.

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 description maps 'kind' to the four enum values, adding meaning beyond the schema. However, it does not explain the optional parameters 'detail', 'projectId', or 'toolContext'—when or why to include them. Given 0% schema coverage, this is a partial but not complete compensation.

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

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

The description opens with a specific verb and resource: 'File a note to the VarynForge team'. It enumerates four concrete types (bug, missing capability, friction, operator idea) that map directly to the 'kind' enum, making the tool's purpose unmistakable and distinct from all sibling tools.

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 when-to-use triggers: hitting something VarynForge cannot do, confusing tool results, or operator frustration/wishes. Also gives clear exclusions ('Do NOT file entitlement walls') and explicitly states it is not a ticket, preventing false expectations.

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 fully carries the transparency burden and excels: it discloses the 1.25× boost for top-10 ranks, the normalization side effect that can change relative rankings despite unchanged raw scores, the cross-check via get_opportunity_detail, and the hiding effect of 'ignored' on competitor surfaces and the editorial-score pipeline.

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

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

Three sentences deliver high-value information with zero filler. The most important action ('Mark a competitor important, default, or ignored') is front-loaded, followed by precise scoring behavior and the hiding effect. Every clause 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?

Given the tool's moderate complexity, no output schema, and no annotations, the description is remarkably complete. It covers the action, all enum effects, scoring side effects, normalization caveat, how to verify raw scores, and the visibility consequences of 'ignored'.

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 thoroughly explains the meaning and consequences of each 'importance' enum value, which is the most semantically rich parameter. It does not explicitly describe projectId and companyId, but their purpose as UUID identifiers is reasonably inferable from 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 opens with a specific verb and resource: 'Mark a competitor important, default, or ignored.' It clearly distinguishes this mutation tool from sibling competitor tools like list_competitors, add_competitor_by_domain, and get_competitor_detail by stating exactly what state it changes.

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 conveys when the tool is relevant by explaining the behavioral effects of each importance value, especially the scoring boost and hiding behavior. It doesn't explicitly state exclusions or alternatives, but the context is clear enough that an agent can infer when to use it versus other competitor-related tools.

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

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

With no annotations, the description fully discloses behavior: terms are down-weighted in scoring, dropped from content-plan harvest, the list is wholly replaced ([] clears), and exclusions survive research re-runs. This goes well beyond a basic 'set' statement.

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 concise sentences: definition, behavioral effect, and lifecycle. No filler, front-loaded with the action, and every sentence adds value.

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

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

Despite having no annotations or output schema, the description covers the operation, side effects, replacement behavior, and persistence. This is complete for a simple setter 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%, but the description defines 'terms' meaningfully with examples and replacement semantics. 'projectId' is implied by 'project-level' and its UUID format is in the schema. Good compensation for the lack 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 clearly states the tool sets project-level exclusion terms, with specific examples (e.g. "wedding suite", "free template"). It distinguishes from per-cluster dismissal by noting persistence, making its unique purpose evident.

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 explains when to use these exclusions (for products/topics not sold) and contrasts with per-cluster dismissal for persistence. However, it does not name other alternatives like set_opportunity_status, so it is clear but not exhaustive.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals that dismissed clusters are hidden from two specific tools, that dismissal is temporary, and that removing a cluster alters the 0-100 normalization of remaining clusters. This is substantive side-effect disclosure, though it stops short of discussing permissions or reversibility beyond status=default.

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

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

Three sentences deliver the core purpose, side effects, duration, and an alternative. Information is front-loaded with the verb and resource, and every sentence contributes meaningful detail without redundancy.

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 mutation tool with no annotations and no output schema, the description covers the key behaviors, parameter semantics, and an alternative path. It doesn't explain the return value, but that is not necessary given the absence of an output schema. The side-effect on normalization shows awareness of broader context, making it sufficiently 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?

The description explains the 'status' parameter thoroughly (dismissed vs. default) and connects it to observable behavior. 'projectId' and 'clusterId' are not described in detail, but their meaning is inferable from the phrase 'opportunity cluster' and the schema's uuid format. Given 0% schema description coverage, the description compensates well for the most nuanced parameter.

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

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

The description opens with a specific verb+resource: 'Dismiss or restore an opportunity cluster.' It clearly explains the two status values and their effects, and differentiates from the sibling tool set_excluded_terms by noting the durable alternative.

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 clear usage context: temporary dismissal until the next research run, and explicitly points to set_excluded_terms for a durable 'not my product' signal. It doesn't enumerate all when-not-to-use scenarios but gives a strong alternative and temporal boundary.

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?

Even without annotations, the description discloses key behavioral traits: it consumes one credit, returns a runId for polling, and returns an entitlement on the free plan. It also implies a write operation (writes opportunity clusters). This adds significant transparency beyond the bare 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 concise and well-structured. It front-loads the core purpose, then adds cost and return behavior in separate short sentences. Every sentence earns its place with no redundant 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 one-parameter tool with no output schema or annotations, the description covers the essential context: what it does, costs, return values, polling mechanism, and free-plan behavior. It could mention error scenarios or whether a research run can be started multiple times, but the current level is strong for this simple 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?

The schema has one parameter 'id' with no description (0% coverage). The description mentions 'for a project' but does not explicitly state that 'id' is the project ID. This is an inference gap; the description should clearly map the parameter to the project being researched.

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 function with a specific verb ('Start'), identifies the resource ('research run'), and outlines the operations it performs ('discovers keywords, evaluates competitors, and writes opportunity clusters'). This distinguishes it from sibling tools that list or update research data.

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

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

The description provides clear usage context: it starts a research run, consumes a credit, and directs the agent to poll get_research_status for progress. It also mentions the free-plan alternative return. However, it does not explicitly state when to choose this tool over alternatives or mention any 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?

With no annotations provided, the description carries the full burden. It discloses important behaviors: setting status to published here records no URL, scheduledFor displays in the app and holds the stalled flag, and publish auto-detect attests and pings IndexNow. However, it does not mention permissions, reversibility, or handling of invalid transitions, so it is 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 dense but efficient, front-loaded with the core purpose, followed by the status list, and then targeted warnings. Every sentence adds value, with no filler or repetition.

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

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

For a state-transition tool with no annotations and no output schema, the description covers the main functionality, the sibling tool handoff, and the scheduling edge case. It could mention return values or what happens on invalid transitions, but overall it is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 0%, so the description compensates by thoroughly explaining the status enum and the scheduledFor parameter with its scheduling implications. It does not mention lastActor or clarify id further, but those are simpler or inferable. The most semantically complex parameters are well covered.

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 moves an article through the production pipeline and enumerates all valid statuses. It explicitly differentiates from the sibling mark_article_published by covering the published transition with a pointer to that tool.

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 provides explicit when-to-use and when-not-to-use guidance: use mark_article_published for the published transition because it records the live URL, and pass scheduledFor when scheduling future publication. It also strongly warns against calling mark_article_published prematurely before the URL is live, which is actionable and 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 are provided, so the description carries the full burden. It discloses the partial-update behavior ('Only the fields you pass are written'), array replacement semantics ('arrays replace the whole list'), the fact that no re-crawl occurs, and a side effect ('Clears the profileStaleAt flag'). This is exemplary behavioral detail for a mutation tool.

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 long and front-loaded with the primary verb and object. Every clause adds information: usage trigger, update semantics, and side effects. It's dense but not bloated, losing a point only for slight complexity in sentence structure.

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 mutation tool with no annotations and no output schema, the description covers the trigger, the update behavior, array semantics, and a side effect. It doesn't mention what the operation returns or error conditions, but it gives enough context for an agent to decide when and how to invoke it correctly.

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

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

With 0% schema coverage, the description names the five profile fields but doesn't explain each parameter's meaning beyond its name. However, it compensates partially by clarifying that only passed fields are written and that arrays replace the whole list, which is crucial for array parameters. projectId and length constraints are left entirely to 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 opens with 'Correct the inferred profile of the project asset' using a specific verb and resource, then lists the five fields it affects. This clearly distinguishes it from sibling tools like update_article_status (article status) or remap_asset (mapping). The purpose is 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?

It provides an explicit trigger condition: 'Use when get_project_asset shows claims that contradict what the operator actually sells (profileStaleAt set, or the operator says so).' It also notes a non-behavior ('No re-crawl happens'), but it doesn't name alternative tools or state when not to use it. Still, the main when-to-use is clear.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It usefully states that omitted fields keep their current values, indicating a partial update. However, it does not discuss permissions, response behavior, or the fact that 'name' is required by the schema, which could be misread when 'omitted fields' is said without qualification.

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 two sentences, front-loaded with the action, and every phrase adds value. It concisely states the resource, the fields, the usage context, and the update semantics without any 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?

For an 8-parameter update tool with no output schema and no annotations, the description is quite complete: it names the fields, gives the workflow trigger, and explains omitted-field behavior. The only notable gap is not acknowledging that 'name' is required by the schema, but that is recoverable from the structured schema.

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

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

Schema description coverage is 0%, so the description must compensate. It enumerates the updatable fields, mapping to schema properties, and clarifies the partial-update semantics. Yet it does not define domain-specific fields like coreProblem or targetCustomer beyond their names, and the schema itself provides no 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 uses a specific verb ('Update') and resource ('niche profile'), lists the key fields, and clearly differentiates from sibling tools like update_asset_profile and update_article_status. It leaves no doubt about what the tool 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?

The description gives a clear when-to-use trigger: 'after the operator refines their market definition.' It does not mention alternative tools, but the unique 'niche' resource and direct update purpose make the context sufficiently clear. Missing explicit when-not-to-use guidance prevents a 5.

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