VarynForge

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

Beyond the minimal readOnly/destructive annotations, the description discloses concrete state changes: verbatim provenance storage, placement into generating_brief, automatic brief creation, free-tier daily-cap queueing, and the return of a suggestionId. This gives the agent a realistic model of side effects and edge 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 sentences with the main action front-loaded and the consequential details packed compactly. There is no filler, no repetition of schema metadata, and every clause adds meaningful 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 is complete about workflow state, return value, and free-tier behavior, and explicitly stating the suggestionId return is important because no output schema exists. It is less complete on input-field semantics, but the upstream expand_idea relationship mitigates that for the intended pipeline usage.

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 only 10%, yet the description does not explain required parameters such as angle, searchIntent, title, or context. It only implicitly references ideaText through 'expanded idea', leaving six required fields poorly documented from the agent's perspective.

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 first sentence names the exact action ('Commit'), the input ('an expanded idea'), and the concrete outcome ('brief-ready article suggestion' in the content plan). It explicitly ties the tool to expand_idea, which clearly distinguishes it from the many sibling suggestion-related 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?

The description tells the agent this is the intended follow-up to expand_idea, so the workflow position is clear. It does not explicitly state when to prefer alternatives like add_article_suggestion or create_article_suggestion_with_input, but the context is strong enough for most routing decisions.

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

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

Annotations already communicate readOnlyHint=false and destructiveHint=false, and the description reinforces a non-destructive mutation by saying 'add to a content plan.' It does not disclose extra behavioral details such as duplicate handling or resulting suggestion state, but the bar is lowered by the annotations and no contradiction exists.

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 no filler. The core action is front-loaded and the sibling routing is saved for the second sentence, making it easy to scan and act on.

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 adequate for a simple create-like operation, especially with the sibling routing and annotations. However, it omits guidance about the required context parameter, which is unusual enough that an agent may misinterpret it without reading the schema carefully; this leaves a real but not fatal 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 only 17%, so the description must compensate; it only explains title, intent, and reasoning. Required parameters like contentPlanId, projectId, and especially context are not clarified in the description, and the context field's unusual semantics (operator's goal, not tool's purpose) is 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 a specific verb and resource: adds an article suggestion to a content plan, and clarifies the payload as title plus optional intent and reasoning. It also distinguishes itself from create_article_suggestion_with_input, so an agent can immediately tell the two closest siblings apart.

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 names the alternative tool, create_article_suggestion_with_input, and gives the decision criterion: use that tool for richer input that produces a brief-ready suggestion. This clearly implies when to use the current tool and when to route elsewhere.

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

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

Annotations only say readOnly=false and destructive=false; the description adds that the tool creates a competitor and marks its importance at creation. It does not disclose duplicate-domain behavior, idempotency, or failure modes, so the behavioral picture is incomplete.

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

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

Two short sentences with no filler. The core action is front-loaded, and the side-effect detail about importance 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 mutation tool with four required parameters and no output schema, the description is adequate but lean. An agent can determine what to pass, but it has no guidance on return values, duplicate handling, or what happens if the project or domain is invalid.

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 only 25%, so the tool description carries weight. It clarifies that domain is a website address and that importance is set to 'important' or 'ignored' on creation. projectId is left mostly to inference, but the phrase 'to a project' anchors its 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 states a specific verb ('Add') and resource ('competitor to a project') and narrows the method to 'by domain' with a concrete example. It also explains that creation assigns an importance state, which differentiates it from sibling tools like set_competitor_importance.

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 use case is reasonably clear: add a competitor when you have a domain and want it tracked in a project. However, it does not explicitly mention alternatives such as set_competitor_importance for later changes, nor does it explain when not to use this tool.

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

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

The annotations only indicate read/write and non-destructive behavior; the description adds substantial behavioral context: naming rules per type, what 'detected' vs 'planned' means, how the destination anchors briefs/drafts/lint, the 10-destination limit, and the confirmation requirement. This goes well beyond what annotations or schema alone convey.

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: every sentence earns its place by covering purpose, state-specific usage, naming rules, confirmation, downstream impact, and capacity limits. It is front-loaded with the core action and resource.

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 main domain complexities well: destination states, naming conventions, operator confirmation, project limits, and the impact on downstream workflows. Minor gaps include lack of return/error behavior and the undocumented 'open' state, but these are modest given the overall richness.

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 adds real meaning for `type` (example values), `name` (domain/handle conventions), and `state` (detected vs planned semantics). However, it does not mention the 'open' enum value and does not explain the required `context` parameter, though the schema already provides a description for `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: 'Add a destination to a project — where the operator publishes.' It clearly identifies the domain object and its role, making it easy to distinguish from list_destinations and other add_* 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 clear conditional guidance for state='detected' vs state='planned', including name conventions and an explicit instruction to confirm with the operator. It does not explicitly name alternative tools or state when not to use this tool, but the context is strong enough to route an agent correctly.

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

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

Beyond the minimal annotations, the description discloses important side effects: auto-creating the content plan, landing suggestions in generating_brief, automatic brief forging, free-tier queueing past the daily cap, and duplicate-title skipping. These are exactly the behavioral details an agent cannot infer from readOnlyHint/destructiveHint.

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

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

Four dense sentences each earn their place: the core operation, how to obtain inputs, the side-effect warning, and the return value. No filler or repetition of schema 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 state-changing tool with no output schema, it covers the required call sequence, side effects, duplicate behavior, free-tier constraints, and return value. An agent has enough context to select and 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?

Schema coverage is low at 17%, so the description compensates by explaining where key parameter values come from: angles from expand_radar_topic and signalObservationId/topicIndex from list_radar_topics. It also gives projectId context via plan auto-creation. The optional topicAngleTotal still relies on its name and schema, so the compensation is strong but not exhaustive.

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 action: adding selected radar-topic angles to the content plan as radar-born article suggestions. It adds distinguishing scope details—provenance preserved and exact-title duplicates skipped—and clearly differentiates this from generic suggestion tools by linking it to 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 gives a concrete invocation path: call list_radar_topics first to obtain signalObservationId and topicIndex, and take angles from expand_radar_topic. It also provides an explicit exclusion—do not also call generate_article_brief—so an agent knows when to avoid a sibling tool.

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

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

The description discloses meaningful behavior beyond the annotations: it runs one live Google search per target keyword, conditionally omits opportunity score and cluster placement when no completed research run exists, and notes credit consumption and daily/monthly caps. The annotations only say readOnlyHint=false and destructiveHint=false, so this additional context is valuable and not contradictory.

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

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

Four dense sentences with no filler. The core behavior is front-loaded, followed by usage sequencing, conditional outputs, exclusions, and cost/rate information — each 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?

For a tool with three required parameters and no output schema, the description is unusually complete: it explains inputs, expected outputs, conditional behavior, when to use it, when not to use it, and account-level limits. Nothing critical for an agent to select and invoke this tool correctly appears missing.

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

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

Schema coverage is low at 33%, but the description partially compensates by clarifying that the tool acts on 'one article idea that is already in the project,' which maps to suggestionId and projectId. The context parameter is already well described in the schema itself. The description does not fully walk through each parameter, but it adds enough relational meaning to be useful.

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 and resource: 'attach real search data to one article idea that is already in the project.' It also names concrete outputs — 'volume bands and the pages currently ranking for each' — and explicitly contrasts itself with start_research_run, so an agent can distinguish it from siblings without opening schemas.

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 sequencing: 'Use after create_article_suggestion_with_input, or on any existing suggestion the operator wants judged on data instead of instinct.' It also names the alternative for a different use case: 'Do not use to find new ideas or map a niche — that is start_research_run.' This leaves little 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 only readOnlyHint=false and destructiveHint=false in annotations, the description carries the burden and discloses key side effects: auto-resolving a default content plan, creating/linking search-query rows for keywords, and returning suggestionId + contentPlanId. It does not however disclose failure behavior, idempotency, or duplicate-creation behavior, so it is not a 5.

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

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

Three tight sentences lead with the main action, then give side effects/return values and the free-tier condition. No filler or repetition; 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?

For a 10-parameter tool with no output schema, the description gives the core action, side effects, and return IDs, but it does not cover the semantics of the optional parameters or the default-content-plan behavior. It is sufficient for a basic call, but not fully complete for advanced usage.

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 only 10% (only the context parameter is described), and the tool description does little to explain the other nine parameters. It references 'keywords' broadly and 'operator's own input,' but angle, reasoning, searchIntent, targetAudience, wordCountTarget, and secondaryKeywords remain semantically 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 opens with a specific verb and object: 'Create a brief-ready article suggestion from the operator's own input.' It further differentiates the tool by noting that it auto-resolves a default content plan, links search-query rows, and requires no research run, which helps distinguish it from siblings like start_research_run or create_content_plan_from_opportunities.

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 clearly indicates when to use this tool: when the operator has their own input and wants a brief-ready suggestion on the free tier ('no research run required'). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for routing.

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?

Discloses meaningful side-effect behavior beyond the annotations: it auto-creates article suggestions, harvests a limited set of top-30 clusters, and applies three explicit exclusion rules. This matches the annotations (readOnlyHint=false, destructiveHint=false) and adds substantial context about what the tool will and will not touch.

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, front-loaded with the core action, followed by linked side effects and exclusion rules. Every sentence earns its place 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?

Covers prerequisites, scope, side effects, and exclusions thoroughly for a two-parameter tool. It does not state what the tool returns (e.g., IDs of created article suggestions), and there is no output schema, which is a minor gap.

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

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

The description does not directly explain either parameter, and schema coverage is only 50%. However, projectId is reasonably inferable as the project with a completed research run, and the context parameter is well documented in the schema. Acceptable but the description adds no parameter-level 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?

States a specific verb and resource: creates a content plan by harvesting top-30 opportunity clusters from a completed research run. It also distinguishes itself from single-suggestion creation by noting it auto-creates article suggestions linked to each cluster.

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?

Implies when to use it (after a completed research run) and explicitly states what is left out: dismissed clusters, excluded terms, and already-covered clusters. It even names related siblings like set_opportunity_status and set_excluded_terms, though it does not fully enumerate alternative tools for all situations.

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

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

The description substantially extends the annotations: it reveals the tool is non-blocking ('Returns projectId immediately; niche analysis and asset mapping run async'), prescribes a polling contract ('Poll get_project until niche.analysisStatus is ready'), and discloses the default org behavior ('defaults to the personal organization'). These behaviors are not visible in the annotations (readOnlyHint=false, destructiveHint=false) or the schema, so the description carries the full burden and delivers.

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

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

Four sentences of dense, operational prose with no filler. The core action is front-loaded, followed by the async return behavior, the polling instruction, and the siteRelation rule — each sentence earns its place and reads as a crisp runbook.

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 9-param tool with no output schema, the description covers the critical ground: return value ('Returns projectId immediately'), async lifecycle, polling protocol, and the siteRelation decision rule. Gaps remain — the required context param is never mentioned in the description, and the alternative input paths (extras, originType, originInput, originDescription) are silently absent — but the primary workflow an agent needs is fully specified.

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 only 11%, so the description must compensate — and it does for some params: it clarifies website/nicheDescription ('pass either a website URL or a niche description'), defines each siteRelation enum value (mine/client/prospect), and explains organizationId's default. However, it leaves several params undocumented in both schema and description: the required context param, plus extras, originType, originInput, and originDescription. The compensation is partial, not complete.

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 — 'Create a new project — pass either a website URL or a niche description (or both)' — and goes on to describe the async flow, making it unmistakable what this tool does. It differentiates itself from siblings by naming get_project as the polling target and list_organizations for org context, so an agent can distinguish it from the many get_/list_ tools nearby.

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 operational context: what inputs to provide (website URL, niche description, or both), when to poll get_project, and how to handle siteRelation ('ask only if it is ambiguous, never guess'). It references sibling tools (get_project, list_organizations) for follow-up steps but does not explicitly state when not to use this tool or name direct 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?

Annotations already declare destructiveHint=true, so the description adds real value by disclosing the breadth of the deletion: the associated brief and cascading effects to keyword and cluster links. It does not fully define what 'cascades' does to those links, but it is still useful behavioral context beyond the annotations.

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

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

Two short sentences with no filler. The primary action is front-loaded, and the second sentence earns its place by warning about side effects.

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 destructive tool with two parameters and no output schema, the description covers what is deleted and what cascades. It could mention irreversibility or expected return value, but the destructiveHint annotation already communicates danger, so the definition is largely 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 documents 'context' fully but leaves 'id' semantically bare except for its UUID format. The description implies that id identifies the article suggestion to delete, adding modest meaning, but it provides no explicit parameter-level detail. With 50% schema description coverage, this is adequate but not strong.

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 ('Delete') and resource ('article suggestion') and adds the key scope: 'its associated brief. Cascades to keyword and cluster links.' This clearly distinguishes it from sibling read/create tools such as get_article_suggestion and add_article_suggestion.

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 intended use is implied by the verb 'Delete' and the cascade note, but the description never explicitly says when to use this tool versus alternatives such as update_article_status or set_opportunity_status. No when-not-to-use guidance is provided, leaving the agent to infer selection.

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?

Discloses the key behavioral traits: returns a single markdown string, ~8K char cap, markdown only, and omits structured fields. Although annotations don't declare read-only, the description is transparent about output and scope; it just doesn't discuss error cases or side effects.

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 dense sentences, front-loaded with purpose, then invocation details, then output behavior. No filler or repetition of schema 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?

Given there is no output schema, the description adequately describes the return value, size cap, and format. It covers the main invocation choices and sibling routing; the only gap is not explicitly addressing how format values other than markdown_inline are handled, but the instructions are sufficient for a correct call.

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 only 20%, but the description compensates by explaining format=markdown_inline and the channel parameter's default and per-channel role. The IDs are self-explanatory and context is already described in the schema, though the description could have tied them together more explicitly.

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

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

States a clear verb+resource ('Get a brief as inline markdown') and the intended use (writing prompt for the host agent). The final clause differentiates it from get_article_brief by saying structured fields are omitted, so an agent can tell 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?

Gives explicit call guidance: pass format=markdown_inline and channel, notes article default. Names the sibling get_article_brief as the place for structured fields, providing a clear when/not-this-tool 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?

The description adds meaningful side-effect context by stating 'without writing anything to the plan', which is valuable beyond the annotations. It also discloses the exact output fields returned. Since readOnlyHint is false, the description narrows the side-effect profile to plan writes, but does not fully clarify whether any other persistence or logging occurs.

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, with every sentence earning its place: the first states the core action and side-effect boundary, the second enumerates outputs, and the third gives the follow-up workflow. It is front-loaded and free of fluff or redundant restatements of the tool name.

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

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

Given there is no output schema, the description appropriately lists the returned fields, which is essential for an agent to use the result. It also explains the no-write behavior and the relationship to accept_idea. It does not specify formats for the 'coarse demand estimate' or 'search intent' values, but the overall picture is sufficient for calling this tool correctly.

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

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

Schema description coverage is only 33%, so the description must compensate. It partially does by referring to 'raw article idea' and 'project's niche', which map to ideaText and projectId, but it never names the parameters explicitly and says nothing about the required context param. The context schema description helps, but the overall parameter guidance remains incomplete.

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') with a clear resource ('a raw article idea') and scope ('against the project's niche'). It also explicitly states the tool does not write to the plan, and the returned fields are named. This distinguishes it from accept_idea, which commits the idea, and from other 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?

The description gives a clear workflow: use this tool to score an idea without writing, then pass the returned fields to accept_idea to commit it. This provides a useful sequencing cue and names the relevant alternative. It does not explicitly discuss when-not-to-use or other alternatives like check_idea, but the context is clear enough for selection.

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

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

The description states 'No writes', but the annotation readOnlyHint: false indicates the tool is not guaranteed read-only. This is a direct contradiction between the free-text description and the structured annotation, requiring a score of 1 per the rubric. The near-duplicate flagging detail is useful but cannot compensate for the contradiction.

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 and front-loaded: the primary action, resource, and output appear immediately. Every clause adds useful information, and there is no filler or redundant restating of the tool name.

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

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

The description covers the tool's inputs, output shape, optional parameter, duplicate-flagging behavior, and handoff to add_radar_topic, which is enough for an agent to call it correctly. It does not detail failure behavior or fully explain projectId/context, but the schema already describes context and the overall usage is clear.

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 only 20%, so the description must compensate. It meaningfully explains signalObservationId + topicIndex as the identity of the radar topic from list_radar_topics and clarifies that customPov is optional and controls the point of view. projectId is not described, but it is a conventional required identifier, and the required context parameter has a schema description.

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 (expand), a clear resource (one radar topic), and the concrete output: 3-6 candidate article angles with title, intent, and editorial positioning. It also differentiates the tool from siblings by referencing list_radar_topics as the source and add_radar_topic as the downstream destination.

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 'No writes — pass chosen angles to add_radar_topic', which tells the agent when this tool is not the right final step and routes it to the sibling that follows. It also states that the inputs come from list_radar_topics, giving clear usage context.

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

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

This is a write operation, and annotations only say readOnlyHint=false and destructiveHint=false. The description goes far beyond that by disclosing idempotency per channel, the free derivation rule, quota behavior, the daily cap returning { entitlement }, and regeneration semantics with guidance.

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 earns its place: channel templates, one-brief-per-channel behavior, derivation, force, guidance, and quota behavior. It is front-loaded with the core purpose and uses backticks and examples for clarity without waste.

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 6 parameters, 5 channel variants, and nuanced quota/derivation rules, the description covers the full behavior landscape. Although there is no output schema, the only output mentioned is the entitlement cap response, which is acceptable given the rich success-path context already provided.

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 only 17%, but the description adds substantial meaning for channel (enumerating template types), force (regenerate idempotently), and guidance (corrective direction). It does not explain projectId/articleSuggestionId, but those are inferable as IDs; overall it compensates well for the 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 opens with a specific verb and resource: "Forge a writer-ready brief from an article suggestion." It explains what the tool creates and differentiates it from read/export siblings like get_article_brief and download_brief_markdown by focusing on generation.

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: channel selection, derivation rules, when to pass force, when to pass guidance, and free-tier limits. It does not explicitly name alternatives or state when not to use this tool, but the behavioral context effectively routes the agent.

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 readOnlyHint=true already provided, the description adds substantial behavioral context: it defines the organization scope of the payload, per-organization caps, the lint_draft daily cap applying on every tier, and the cross-project next_actions queue. This goes well beyond the annotation and helps the agent understand the tool's data semantics and operational timing.

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 front-loaded with the core purpose, and every parenthetical serves a concrete operational purpose, such as referencing list_organizations or checking remaining allowances. It is longer than average, but the enumeration of return fields and usage caveats earns the 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?

Given there is no output schema, the description must carry the burden of explaining what the tool returns, and it does: plan, credits, quota, caps, locked tools, upgrade URL, next_actions, plus the default-organization behavior and when to pass organizationId. It is fully actionable for an agent deciding whether and how to call this tool.

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

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

The schema describes the context parameter clearly, but organizationId only has length constraints with no semantic description. The description compensates by explaining that organizationId selects the organization whose caps apply, and defaults to the personal organization. This is meaningful added meaning, though the context parameter's semantics are primarily carried by 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 a specific verb ('Get') and resource ('account status'), then enumerates the exact fields returned: plans, credits, quota state, lint_draft cap, idea_checks allowance, locked tools, upgrade URL, and next_actions. This level of specificity clearly distinguishes it from sibling tools like list_organizations and get_changelog.

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 states when to call it: 'Read on session start and after a wall hit.' It also explains when to pass organizationId ('when working a project that belongs to a different organization') and directs the user to check allowance fields before verification/check loops, giving actionable routing 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 readOnlyHint already declared, the description adds substantial behavioral detail: the per-channel brief model, compact dropping referenceArticles, guaranteed populated fields, and the exact fallback object with hasBrief: false and statuses queued/forging/none plus queuedUntil. It even explains polling after queuedUntil. This goes well beyond the annotation baseline.

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?

Each sentence adds distinct information: purpose, channel selection, brief fields, compact behavior, guaranteed fields, and fallback semantics. The description is dense but front-loaded with the purpose and the most critical details. No filler or redundant repetition of schema 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 no output schema, the description covers the main return expectations: hookStatement, keyStats, referenceArticles, and the fallback object. It doesn't enumerate every field of a full brief, but it provides enough for an agent to invoke and interpret the result correctly. The missing-brief scenario is explicitly described, which is important for handling edge cases.

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 only 25% (only context is described), so the description carries the burden. It thoroughly defines channel values and default, and explains compact's effect on referenceArticles. SuggestionId is only implied as the suggestion identifier, but its meaning is inferable from the tool's purpose and the sibling get_article_suggestion.

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 'Get the full content brief for an article suggestion', stating a specific verb and resource. It differentiates from sibling tools like generate_article_brief by focusing on retrieval of an existing brief, and explains the per-channel structure. This is unambiguous and distinct.

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 clearly implies this is the read path for existing briefs, with explicit guidance on channel selection and the behavior when a brief doesn't exist. It does not name sibling tools like generate_article_brief as alternatives, but the context is clear enough for an agent to decide when to call it. No exclusions are given, but the usage context is well established.

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

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

Annotations already mark readOnlyHint=true, so the description does not need to restate safety. It adds genuinely non-obvious behavior: what generating_brief with and without briefQueuedAt means, specifically queued behind the daily cap versus actively forging. That goes beyond what annotations or schema provide.

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 with no filler; the first sentence front-loads the resource and payload, and the second adds critical status disambiguation. 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?

With no output schema, the description lists the major output groups and explains the non-obvious queued-brief semantics, which is enough for an agent to know what it will get. It does not spell out all possible statuses or exact field names, but nothing essential for a correct call is missing given the read-only annotation and self-explanatory parameter names.

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 does not mention either parameter or explain how to get or validate suggestionId; the schema only provides format and pattern but no description, and the 50% coverage means the description was expected to compensate. 'context' is already described in the schema, but no additional meaning is added for the required ID.

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') and enumerates exact payload areas: metadata, cluster context, brief availability, derived assets, target keywords with volumes. It also separates itself from get_article_brief by directing full-brief requests there. This leaves no ambiguity about what the tool returns.

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 includes an explicit routing instruction: 'Call get_article_brief for the full brief,' which tells an agent when this tool is not the right choice. The status semantics for generating_brief also explain how to interpret a result that may be queued rather than ready. This is clear usage guidance for the most likely confusion among siblings.

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

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

Annotations already mark readOnlyHint=true; the description complements this by stating that the result is a URL to a plain-markdown changelog ordered newest first. This adds useful behavioral detail about the returned artifact without any contradiction.

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, no filler: the first states exactly what the tool returns, and the second gives concrete use cases. All content 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 single-parameter, read-only tool with no output schema, the description is complete: it specifies the returned artifact (URL), the content of that artifact, and when to call it. Nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%, and the context parameter is well explained in the schema as a one-sentence operator goal. The tool description does not add parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Get the URL of the VarynForge product changelog') and immediately adds discriminating detail ('what shipped, newest first, in plain markdown'). This makes it clearly distinct from the many other get_* siblings, none of which target a changelog.

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 states explicit triggers: fetch it when the operator asks what is new, and in the days after a send_feedback report to check closure. It lacks an explicit when-not-to-use or named alternative, so it stops short of a full 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?

The annotation readOnlyHint=true already declares the safe read-only nature, so the description only needs to add extra behavioral context. It adds the specific return fields and project scoping, which is useful, but it does not describe error scenarios, permissions, or pagination behavior. This is acceptable for a simple getter but not exceptional.

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 concise sentence that front-loads the action and project context while listing the key return fields. There is no redundant or filler 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?

Given the tool's simple get-by-ID purpose, the description covers the return values adequately even without an output schema. It names the main outputs and project scoping. A slightly richer explanation of what happens when the competitor is not found would improve completeness, but the core information needed to invoke it correctly is present.

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 only 33%, with only the context parameter explained. The description mentions 'project context' but does not clarify the roles of companyId and projectId beyond their self-evident names and UUID format. With low coverage, the description should compensate more explicitly for the undocumented parameters, but it does not.

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 that the tool retrieves a competitor company detail within a project context and enumerates the returned fields (domain, name, importance, top SERP pages, top keywords). It is specific about the verb and resource, but it does not explicitly differentiate this tool from siblings like list_competitors or set_competitor_importance.

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 no guidance on when to use this tool versus alternatives such as list_competitors or get_keyword_detail. It implies a detail lookup but does not state conditions, exclusions, or alternative 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?

Although readOnlyHint is already true, the description adds materially beyond annotations: the tool is 'free and uncapped,' it returns per-destination receipts plus a single pipeline status, and it explains the forward-only status-ownership model where one destination's later failure cannot demote another destination's ready_to_publish state. This is non-obvious behavioral context that prevents misinterpretation.

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 earns its place: the first sentence defines the resource and output shape, the second gives usage priority, the third explains the format parameter, and the fourth clarifies the ownership model. The most important scoping constraint is front-loaded without burying the key 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?

There is no output schema, so the description must explain the return shape, and it does: pipeline status, per-destination format, stored draft, gate receipt, verdict, per-check detail, and thresholds. Combined with the clear parameter guidance and the readOnlyHint annotation, nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema coverage is only 33%, so the description carries meaningful weight for parameters. It clearly explains format's semantics (include draft text vs. overview-only) and ties suggestionId to 'an article suggestion,' which is inferable but not explicitly spelled out. The context parameter is already described in the schema, so the description adequately compensates overall.

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: 'Re-read an article suggestion's verification state without re-linting.' It clearly differentiates itself from lint_draft by emphasizing it recovers a known verdict rather than performing a fresh lint, so an agent can immediately identify what this tool does and does not do.

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 is explicit about when to use this tool: 'always use this instead of lint_draft to recover a known verdict.' It also gives concrete decision guidance for the format parameter—pass it to include stored draft text, omit it for the overview—which tells the agent exactly how to tailor the call to the operator's goal.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Get' verb aligns with a read operation. The description adds content context but no additional behavioral traits such as caching, rate limits, or required auth. With annotations covering the safety profile, a 3 is appropriate.

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 with no filler. The core purpose is front-loaded, the guide's contents are listed compactly, and the usage directive is placed at the end. 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 simple read-only tool with one well-documented parameter and no output schema, the description fully covers what an agent needs: what the tool returns, what it contains, and when to call it. Nothing important 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 input schema has 100% description coverage for the single 'context' parameter, so the schema already explains what to provide. The tool description does not add any parameter-level guidance beyond the schema, so baseline 3 applies.

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 ('VarynForge agent guide'), and enumerates the guide's contents (workflow paths, token-economy rules, walls, upgrade conventions). This clearly distinguishes it from sibling get_* tools like get_onboarding_guide or get_lint_rubric, which have their own distinct scopes.

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 'Read this at session start,' giving a clear temporal trigger. It does not mention alternative tools or when not to use it, but the session-start directive provides sufficient context for an agent to know when this is the right call.

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

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

The readOnlyHint annotation already signals safety, and the description adds value by disclosing what the response contains: ranking pages, positions, ownership data, and related keywords. This gives the agent a useful behavioral model of the return payload even without an output 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 a single, front-loaded sentence that immediately names the tool's purpose, then packs the key return elements into a compact list. No filler or redundant restatement of the title.

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 read-only keyword detail lookup, the description covers the main return categories and project scoping. However, with no output schema and an opaque queryHash parameter, the description leaves a meaningful gap around how to construct a valid call and what exact shape the response takes.

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 only 33%. projectId has a format description and context has a plain-language goal instruction, but queryHash is entirely undocumented. The description does not compensate by explaining how to obtain queryHash or how it relates to other keyword tools.

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 ('keyword detail'), then adds concrete detail on what it returns: ranking pages with positions and ownership, plus related tracked keywords. This clearly separates it from list_keywords and other detail-getters.

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 makes it reasonably clear the tool is for inspecting a single keyword's ranking and related keywords, but it does not explicitly state when to use this versus list_keywords, get_opportunity_detail, or get_competitor_detail. Usage context is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with a safe read operation. It adds useful behavioral context beyond the annotation: the rubric content details (checkParams, submission formats, brief fields read) and the fact that channel defaults to 'article'. No contradictions.

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 with no waste: the first delivers the full return payload, the second explains the channel parameter and its consistency requirement, the third gives the workflow position. The most important scoping facts 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?

With no output schema, the description fully compensates by enumerating what the rubric contains. It covers the optional parameter behavior, the relationship to lint_draft, and when to call it in the workflow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is only 33%, so the description carries the burden. It explicitly explains the channel parameter's meaning and default ('article default'), plus why it matters ('use the same channel you will pass to lint_draft'). suggestionId's role is implied by 'for an article suggestion', and context is already self-described 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 names a specific verb and resource ('Get the verification rubric for an article suggestion') and enumerates the exact contents: submission formats, required vs advisory checks, numeric checkParams, and the brief fields lint_draft reads. It clearly distinguishes itself from nearby siblings by naming lint_draft as the downstream consumer, leaving no ambiguity about what this tool returns.

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 workflow guidance: 'Fetch this before writing so the draft passes on the first submission' and instructs the agent to pass the same channel it will pass to lint_draft. It names the companion tool directly, though it does not explicitly state when not to use this tool versus other brief-related siblings like get_article_brief.

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

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

Annotations only declare readOnlyHint=true, so the description carries the burden of behavioral context and does it well. It discloses that the result is server-derived, includes a stage-tailored pitch, a checklist with done/pending status, and a ranked next_actions queue, and it warns against prescribing the welcome pitch prematurely.

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

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

Four sentences with no filler: purpose and trigger conditions come first, followed by return-value summary and a caution. Every sentence earns its place and the structure is easy to scan.

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, read-only tool with no output schema, the description covers when to call, what it returns, and a diagnostic constraint. An agent has sufficient information to select and 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 already documents the sole context parameter at 100% coverage, including the instruction to describe the operator's goal rather than the tool's purpose. The tool description adds no param-specific detail, so the schema-driven baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Diagnose') and a clear resource: where the operator is in their VarynForge journey, plus a guided setup path. This distinguishes it from generic get_* sibling tools by focusing on onboarding and setup diagnosis.

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 call conditions: 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 provides a when-not rule: never run the welcome pitch on an operator whose stage says producing.

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

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

Annotations already establish readOnlyHint=true, so the safe read-only nature is covered structurally. The description adds value by disclosing the specific composition of the response, including the unusual rawOpportunityScore behavior that differs from list_opportunities. No contradictions or hidden side effects 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?

A single, front-loaded sentence conveys the tool's purpose and key output details without filler. Every element adds useful information, and the normalization caveat is placed at the end where it naturally complements the enumerated response 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?

Although there is no output schema, the description enumerates the major return components in specific terms, making the expected result clear. The main gap is parameter guidance, but the schema covers context and the IDs are strongly implied by the tool name and cluster terminology.

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 only 33%, and the description does not compensate by explaining clusterId, projectId, or context. The context parameter is described in the schema, but the other two required parameters have only format constraints, leaving their semantic roles to be inferred from the tool name and general wording.

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-resource pair ('Get a cluster detail') and enumerates exactly what the response contains: top-20 keywords, top-10 ranked pages, top-5 competitors, article suggestions, and rawOpportunityScore. It also distinguishes itself from list_opportunities by calling out the normalized vs raw score difference, which removes ambiguity.

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 names list_opportunities as the alternative and explains the key difference (raw vs normalized score), giving the agent a concrete basis for selecting this tool. It does not provide an explicit 'use this when...' statement or broader exclusions, but the comparison to a sibling tool provides clear context.

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

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

The readOnlyHint already signals a safe read, so the description's main additive value is the disclosure that headingOutline, targetKeywords, and contentAnalysis only populate for owned (asset-mapped) pages. This is a useful conditional behavior, but the description introduces no further behavioral context such as error cases or data freshness.

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 that states the resource, the primary fields, and the conditional caveat in order of importance. Every clause adds information; there is 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?

With no output schema, the description provides only a partial list of return fields and does not specify the full response shape, ownership rules, or error behavior. It covers the core purpose and the most salient caveat, so an agent can call it, but there are remaining gaps for a tool with no structured return info.

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?

Only the context parameter has a schema description (33% coverage), and the tool description itself gives no direct explanation of pageId or projectId or their relationship. The phrase 'page dossier' and the mention of 'project rankings' offer only an implicit hint that pageId targets the page and projectId scopes the project; this does not compensate for the 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 identifies a specific resource ('page dossier') and lists its contents (URL, title, project rankings, ownership), with a clear conditional caveat. It does not explicitly contrast against sibling tools like get_project or get_project_asset, so it misses the top bar for differentiation, but the verb+resource is unambiguous.

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

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

The description implies when the tool is appropriate — when the operator needs a page-level dossier and knows the page/project — and hints that unowned pages yield partial data. However, it provides no explicit 'when to use vs. alternatives' or exclusion criteria, leaving the choice 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?

The readOnlyHint annotation already marks this as safe, and the description adds substantial non-obvious behavior: the opportunity map holds gaps only, no search-volume numbers by design, covered opportunities must never be pitched as new work, covered clusters never enter the 90-day sequence, incomplete runs return null report, and the renderGuide requires operator branding. This goes far beyond the structured annotations.

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

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

The description is very long and written as a dense single paragraph with many embedded parentheticals. It front-loads the purpose but buries the key invocation guidance toward the end, and includes less essential details like 'Included with every run, no extra cost.' The content is valuable but would benefit from structured bullets and tighter editing.

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 read-only tool with no output schema, the description is unusually complete. It defines the payload structure, conditional behaviors, the null result for incomplete runs, the resync choice, rendering expectations, and the runId source. An agent has enough context to select and invoke the tool correctly without additional lookups.

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 describes the context parameter well, and the description adds the critical runId semantics: it must come from get_research_status and must reference a completed research run. Since only half the parameters are schema-documented, the description partially compensates by clarifying the more operationally important 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 assembles a client-ready pitch report payload for a completed research run and enumerates the major payload components: opportunity map, coveredOpportunities, 90-day content sequence, assetProfile, and renderGuide. It is unambiguous and distinct from sibling getters because it defines a unique output contract and even names get_research_status as the source of the runId.

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 context: use with a completed research run and pass the runId from get_research_status. It warns that an incomplete run returns { runStatus, report: null }, and it provides a conditional alternative by offering resync_asset_profile when assetProfile.syncedBeforeRun is true. It does not enumerate all sibling exclusions, but the usage 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 readOnlyHint=true already declaring the operation is non-mutating, the description adds behavioral context beyond the annotation: it defines fallback logic for the canonical name (operator-set, falling back to site brand then niche name), clarifies field semantics (`niche.name` is not the project name), and ties postsPerWeek to pitch report sizing. It does not dwell on return structure, which is acceptable since there is no output schema but the description already describes the key returned fields. This is a meaningful contribution beyond the annotation, so a 4 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 compact and information-dense: two sentences cover the resource, returned fields, a cross-reference to set_posting_cadence, and the critical `name` vs `niche.name` distinction. Every clause earns its place, and the most decision-relevant facts (what is returned and how to address the project) 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?

For a read-only fetch with two parameters and no output schema, the description conveys the key returned fields, the project-addressing convention, and the postsPerWeek/pitch-report relationship. It lacks an explicit statement about the `context` parameter's role or an explicit exclusion of sibling tools, but the definition is sufficient for an agent to correctly select and invoke the tool. Given the simplicity of the tool and the annotation coverage, this is a minor gap rather than a major omission.

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 50%: `context` is documented in the schema but `projectId` is not. The description compensates partially by clarifying which project field to use (`name` vs `niche.name`) and by explaining the meaning of `postsPerWeek`, but it does not explain the `context` parameter's intended input beyond what the schema already says. Since the description adds value beyond the schema for the semantics of the returned project data and clears a naming trap, it rises above the baseline 3, though it could have explicitly explained `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 'Get one project' and enumerates the specific fields returned: canonical name, niche profile, target audience, research status, and postsPerWeek. It also clarifies that the project is addressed by `name` and warns that `niche.name` is not the project name, which is a useful disambiguation. This clearly identifies the tool's resource and differentiates it from sibling tools like get_project_overview 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 explains that postsPerWeek is the operator's publishing cadence and notes that it is settable via set_posting_cadence, implying when this read tool is relevant for sizing pitch reports. However, it does not explicitly state when to prefer this tool over sibling alternatives such as get_project_overview or get_starting_point_report, so exclusions are only implicit. That keeps it just below 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?

The readOnlyHint annotation already establishes that the call is safe, and the description adds what the caller will receive: URL, name, description, and solution profile. This is useful because there is no output schema to carry that information.

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

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

A single front-loaded sentence with no filler; the core action and return fields are in the first clause. All content 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 simple read operation with only two parameters, the description provides enough information to understand the return value, and the schema handles the parameters. It could be more complete by clarifying what 'solution profile' means or how the context parameter affects the call, but nothing critical is missing.

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

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

Schema description coverage is 50%: context has a description, but projectId only has a UUID format/pattern. The tool description adds no explanation of either parameter, though projectId is largely self-explanatory and context is already documented.

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-resource pair ('Get the asset ... associated with a project') and enumerates the returned fields (URL, name, description, solution profile). This differentiates it from sibling retrieval tools like get_project or get_project_overview by targeting the website/product asset rather than generic project 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?

No guidance is given about when to call this tool rather than get_project, get_page_dossier, or update_asset_profile. The description states only what the tool does, not the conditions or exclusions that should route an agent to 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?

Beyond the readOnlyHint annotation, it discloses ranking semantics, unscored radar-born suggestions, why score/cluster may be null via source, and which statuses count as done. These details meaningfully affect how the result should be interpreted and acted on.

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 content is front-loaded and each clause carries operational meaning, but the single dense run-on sentence with nested parentheticals is harder to scan than a bulleted structure would be. It is still 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?

With no output schema, the description thoroughly explains the two ranked queues and the critical status-filtering logic, which are the parts most likely to be misread. Minor gaps remain around the exact shape of 'niche summary' and 'keyword stats', though those are reasonably self-evident.

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 adds no parameter-level guidance; context is already well documented in the schema and projectId is self-explanatory. With 50% schema coverage and no description compensation, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the operation ('get') and resource ('project overview') and enumerates the distinctive content: niche summary, keyword stats, nextActions, and topPriorities. This content is specific enough to separate it from sibling getters like get_project.

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 a concrete trigger ('when the operator asks "what now?"') and explains how to interpret 'do the next piece' using statuses. It does not explicitly contrast itself with alternative tools or state when not to use it, 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?

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral detail: the failure taxonomy (failureClass values), retryable semantics, the stalled-initializing heuristic, and the token-light response shape. This goes far beyond the structured annotation and tells the agent what to expect and how to act on edge cases.

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?

Every sentence carries operational value: the return shape, failure diagnostics, retry guidance, stalled-run detection, and token budget. The description is dense but well-organized, front-loading the core purpose and return fields before edge-case 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?

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly, including failure structure and follow-up actions. It is complete for a read-only polling tool; the only minor gap is parameter semantics, which is already partially addressed by the 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?

The input schema describes context well but projectId only through format and pattern, and schema description coverage is only 50%. The tool description merely says 'for a project' and does not explain the required context parameter or the semantic meaning of projectId, so it does not compensate for the schema gap.

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

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

The description opens with a specific verb and resource: 'Poll the latest research run for a project' and then enumerates the exact returned fields (runId, status, pipeline phase, progress, elapsed seconds, failure diagnostics). This clearly differentiates it from sibling status tools like get_account_status or get_draft_status by naming the resource and 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 establishes a clear polling context and provides conditional guidance: stalled initializing runs should be reported rather than waited on, and retryable failures are safe to retry while non-retryable ones are not. It does not explicitly name alternative tools or state when not to use it, but the polling intent and decision rules are 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?

Annotations already declare readOnlyHint=true, but the description adds meaningful behavioral context: it is a no-research-run report, markdown is the ready-to-send render, structured fields are for custom rendering, and lockedSections lists sections that are absent here rather than previewed. This goes beyond the annotation and gives the agent a clear model of what the tool returns and what it intentionally does not include.

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?

Every sentence earns its place: definition, availability, render semantics, the meaning of lockedSections, and sibling routing. It is front-loaded with the core purpose and remains dense without being padded.

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

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

Even with no output schema, the description tells the agent what data the report contains (positioning, content inventory, competitor set, rising-topic signals), what markdown versus structured fields mean, and what lockedSections represents. It also covers the one important decision point—when to use get_pitch_report_payload instead. The required parameters are documented in the schema, so the description does not need to repeat them.

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 50% because the context parameter has a description but projectId only has format/pattern constraints. The tool description never mentions either parameter by name; "for a project" only weakly maps to projectId, and the required context parameter's meaning is left entirely to the schema. With medium coverage, the description should have added explicit parameter semantics but does not.

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 the free starting-point report for a project," and immediately explains what this report is (a client-facing document assembled from setup-time data). It explicitly differentiates itself from the sibling get_pitch_report_payload, saying "prefer get_pitch_report_payload: that is the full report," so an agent can tell them apart.

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

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

The description gives explicit when-to-use guidance: "Free on every plan, no research run required" and "Once the project has a completed run, prefer get_pitch_report_payload." This clearly states the condition for choosing this tool versus the alternative and leaves nothing 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?

Annotations provide readOnlyHint=true, and the description adds non-obvious behavior beyond that: FAQs cap at 6, long sections degrade to fit a deep-link budget, and deepLinks is null over MCP. It also clarifies that the payload is intentionally compact and not authoritative, which is important for correct use. No contradiction with annotations.

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

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

Four sentences, with the core operation front-loaded in the first sentence and the limitations and alternatives following. Every sentence adds distinct value—contents, truncation behavior, sibling routing, and MCP-specific null behavior—with no filler.

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

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

For a read-only one-call retrieval with no output schema, the description sufficiently covers the return payload, its compact/degraded nature, the deepLinks caveat, and authoritative fallback sources. Combined with the readOnlyHint annotation and clear sibling distinction, an agent has enough context to decide whether 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?

The context parameter already has a clear schema description, but suggestionId only has format/pattern and no description. The tool description does not explicitly map parameters; it indirectly implies suggestionId refers to an article suggestion via the phrase 'for an article suggestion,' but it never states it directly. With 50% schema coverage, this is adequate but not thorough.

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 names the specific operation ('returns a compact writing payload') and resource ('for an article suggestion'), and enumerates the payload contents (brief essentials, keywords, acceptance criteria, lint instructions). It also explicitly distinguishes itself from get_article_brief and get_lint_rubric, so an agent can immediately tell it apart from siblings.

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 names the alternatives (get_article_brief for the full brief, get_lint_rubric for the full check list) and warns to verify against those rather than this compact output. It also discloses that deepLinks is null over MCP, preventing agents from expecting a web-only feature. This is clear when-to-use and when-not-to 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?

Annotations provide readOnlyHint=true, and the description adds meaningful behavioral context: the prompt binds to account context and degrades to generic writing advice without it. It also discloses channel-specific methodology differences, which goes beyond the structured annotation.

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 purposeful, front-loading the tool's purpose then expanding into channel-specific details. Every sentence adds information, though slightly more length than strictly necessary for the simplest reading.

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 gives enough about what the prompt contains and how it varies by channel. It covers the key operational nuance (degradation without account context) and leaves little ambiguity for an agent deciding to call this tool.

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

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

Schema coverage is only 50%, with context described but channel lacking a description beyond enum/default. The description compensates strongly for channel by explaining what each enum value covers and confirming the default, while the context parameter is already adequately described 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?

States a specific verb and resource ('Get the writer system prompt for drafting one content type from its brief'), and immediately differentiates channel-specific behaviors. It clearly identifies what the tool returns and how it relates to the broader drafting workflow.

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

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

Explicitly instructs when to use it ('Load the prompt for the channel you are about to draft') and notes the default channel. It does not name sibling alternatives like get_write_handoff or get_instructions, but the channel-specific guidance makes usage context reasonably 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?

The description goes far beyond the sparse annotations by disclosing state transitions, forward-only status rules, per-format draft replacement, waiver behavior, daily caps, cache behavior, and the script-vs-video gate. This gives the agent an accurate model of side effects and constraints without needing to call the 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 long but every sentence earns its place, covering high-stakes behavior that an agent must know before invoking. The primary purpose is front-loaded, and dense semicolon-separated details keep related concepts together.

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, absent output schema, and minimal annotations, the description is remarkably complete. It documents response fields, parameter behaviors, side effects, edge cases, alternatives, and operational constraints, leaving no critical 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 description coverage is only 17%, so the description carries the burden of explaining parameters. It thoroughly covers channel semantics and submission shapes, format storage implications, and waiveChecks authorization rules. This adds meaning far 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 states a clear verb and resource: 'Submit a draft for verification against its brief' and specifies the pass/flag outcome with per-check detail. It also distinguishes itself from related tools like get_draft_status and get_lint_rubric, so an agent can tell exactly what this tool is for.

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 tells when to use this tool versus alternatives: never re-lint to recover a verdict, use get_draft_status instead, and use get_lint_rubric for numeric limits. It also gives concrete conditions like 'always pass channel for non-article content' and explains when re-submission is 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?

Annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds useful behavioral context beyond annotations: the status semantics for generating_brief (briefQueuedAt set vs null), automatic forging at cap reset, and the recommendation to re-check within a minute. This helps the agent interpret returned statuses 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 dense but every sentence earns its place: return fields, practical gap-spotting use, paging/full-record routing, and status disambiguation. It is front-loaded with the core action and well organized from general to specific.

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 output schema, the description explains the main return shape including the nested distributions rollup, defines status semantics that affect interpretation, and covers pagination and the relationship to the detail tool. This is sufficient for an agent to select and 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?

Schema description coverage is only 20%, so the description carries most of the semantic burden. It clarifies projectId by saying 'for a project', cursor via 'Page through suggestions', and status via the detailed status semantics. Limit is self-explanatory and documented in the schema. The context parameter is already described in the schema, so this is reasonable 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: 'List article suggestions for a project' and enumerates exact returned fields, including the distributions rollup shape. It clearly differentiates from get_article_suggestion by saying to call that tool for the full record, so an agent can distinguish 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?

Explicitly tells when to use this tool vs. the alternative: use the list and its distributions rollup to spot gaps 'without per-item reads', and page through suggestions rather than fetching individually. It also directs to get_article_suggestion for full records, giving clear routing 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?

Annotations only provide readOnlyHint=true, so the description carries the burden of explaining behavior. It adds the exact sort order, the inclusion of unmarked SERP-discovered companies, and the 100-result cap. These are meaningful behavioral details beyond the annotation.

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 four short sentences with no filler. Each sentence contributes a distinct fact: scope, sort order, filtering mechanism, and result cap. The core purpose 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?

For a read-only list operation with a single filter, the description covers the essential behavioral context: what is listed, the ordering, the filtering option, and the maximum result count. There is no output schema, and the description does not describe the return shape, but this is a minor gap for a list 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 low at 25%, and the description partially compensates by explaining the `importance` buckets and the result cap. However, it does not add semantics for `projectId` or `context`, relying partly on the schema and self-evidence. The added value is real but incomplete.

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

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

The description clearly states the verb ('List'), the resource ('companies for a project'), and distinguishes between marked competitors and SERP-discovered unmarked companies. The sorting detail also differentiates it from generic list tools like list_organizations and from 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 provides clear context for when to use the tool: listing a project's competitors, including unmarked ones. It also gives a concrete conditional usage hint ('Pass `importance` to filter to one bucket'), though it does not explicitly name sibling 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?

Annotations only state readOnlyHint=true; the description goes well beyond by detailing what each row contains (briefChannel, verifiable, publishable, publishVia), what each field means, and the empty-list behavior. These behavioral traits are not available anywhere else and exceed the annotation coverage.

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 yet front-loaded with the purpose, followed by a compact breakdown of row fields and edge-case behavior. Every sentence carries operational meaning; there is no filler or repetition of schema data.

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 read-only list tool with no output schema, the description fully covers the return row semantics, the meaning of each capability, and the empty-response fallback. An agent has everything needed to call the tool and interpret its result without further research.

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 50%: context has a full description, but projectId has only format/pattern. The description implicitly clarifies projectId by saying 'the project's destinations,' but it adds no direct explanation of how the context parameter should be used or whether it affects results. This is partial compensation, not complete.

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: 'List the project's destinations' and enumerates the concrete destination types (website, youtube_channel, tiktok, etc.). It also names related sibling tools like add_destination and lint_draft, making the tool's 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?

It gives explicit guidance for the empty-list case: use add_destination or fall back to the brief channel name as the lint_draft format label. It also explains that the row capabilities are self-contained, so the agent knows it does not need to cross-reference other tools for this data.

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

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

Annotations already mark the operation as read-only, and the description adds useful behavioral context beyond that: pagination, support for sorting, the intent filter, and the volume bucket vocabulary. It reveals list semantics without contradicting the readOnlyHint.

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 and front-loaded, covering what the tool lists, the fields returned, volume buckets, pagination, sorting, and filtering in two sentences. No filler or redundant restatement of the tool name appears.

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

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

With no output schema, the description responsibly names the returned fields and pagination behavior. It leaves minor gaps around cursor usage and the exact response envelope, but for a paginated list tool the description is sufficiently complete for correct invocation.

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

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

Schema description coverage is only 17%, so the description must compensate for undocumented parameters. It partially does by mentioning sorting and intent filtering, but it does not clarify cursor mechanics, limit behavior, or projectId semantics beyond what the schema already exposes through names, defaults, and enums.

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 ('List') with a precise resource ('keywords tracked for a project') and enumerates the returned attributes and volume bucket values. This clearly differentiates it from the singular get_keyword_detail and other list tools by 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 gives clear context for when to use the tool: listing project-tracked keywords with pagination, sorting, and intent filtering. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when this list operation is appropriate.

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

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

The description goes far beyond the readOnlyHint annotation by disclosing non-obvious behaviors: default coverage filtering to ['gap','partial'], hiding of dismissed clusters, down-weighting from excluded terms and fit flags, and score normalization that can shift relative numbers. This is exactly the behavioral context an agent needs to interpret results 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 front-loaded with the core purpose and each subsequent sentence contributes unique behavioral detail. It is dense and arguably could be more scannable with bullets, but it contains 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?

The description explains the most important output interpretations — which clusters appear, what is hidden vs. down-weighted, and how scores normalize — but omits return-value structure and pagination behavior, and there is no output schema to fill that gap. The unexplained optional parameters further reduce completeness.

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 adds real meaning to `goal` and `coverage` by explaining default values, filter semantics, and hidden vs. down-weighted effects — valuable beyond the bare schema enums. However, schema description coverage is only 13%, and six other parameters such as cursor, activeMetaCluster, and excludeInContentPlan receive no explanation in the description.

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 'List content opportunity clusters sorted by opportunity score' — a specific verb, resource, and ordering. This unambiguously identifies what the tool does and implicitly distinguishes it from detail-oriented siblings like get_opportunity_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?

No explicit when-to-use guidance or alternative routing is provided. The description references set_opportunity_status and set_excluded_terms only as state influences, not as alternatives, and never explains when to choose this over get_opportunity_detail or create_content_plan_from_opportunities.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it returns membership details and pending invitations, and explicitly notes that accepting invitations must happen in the web app, not through this tool. This clarifies both the data scope and an important limitation without contradicting the annotation.

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 fluff: the first lists output fields, the second explains the organization concept, and the third tells how to apply the result. Every sentence earns its place and the most decision-relevant info 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?

With no output schema, the description compensates well by naming the returned fields and including pending invitations. It also connects this tool to the broader workflow by showing how organizationId feeds into create_project and get_account_status. Nothing critical for a caller 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 only parameter, context, has a full schema description explaining what to provide, so schema coverage is 100%. The tool description itself adds nothing about the parameter, but the schema already carries that burden; the baseline of 3 applies.

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 ('List') and a concrete resource ('the organizations this account belongs to'), then enumerates the exact fields returned (id, name, role, is_personal, plan, member_count). It also distinguishes itself from sibling list_* tools by focusing on organizational membership and pending invitations.

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 explains when this tool's output matters: plans, credits, and usage limits are per-organization, and projects belong to exactly one organization. It gives concrete guidance to pass an organizationId to create_project or get_account_status, though it does not explicitly say when not to use this tool versus an alternative.

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

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

Annotations already declare readOnlyHint=true, and the description consistently describes a read operation. It adds useful context about ranking and project scoping, but does not disclose pagination behavior, default ordering, or how filters and sorting interact beyond the title.

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 tight sentence that front-loads the verb and resource and then packs in the key returned fields and filters. Every phrase earns its place and there is no redundant text.

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

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

There is no output schema and the tool has nested filter/sorting objects plus a cursor parameter, yet the description omits pagination, default ranking, and the full set of filters. The schema compensates partially, but an agent would still need to infer important behavior around optional sorting and cursor usage.

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 very low at 17%, and the description only explicitly maps ownership and companyDomain filters. Most parameters are self-describing through their names and enums, but cursor, minQueryCount, and sorting semantics are not explained in the description, so it only partially compensates 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?

Description uses the specific verb 'List' with a distinct resource ('ranked pages tracked for a project') and enumerates returned fields and filters. This clearly differentiates 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 intended context is clear: use this tool to retrieve tracked pages for a project, optionally filtered by ownership or company domain. It does not explicitly name alternatives or state when not to use it, so it falls just short of full routing guidance.

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

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

Annotations already carry readOnlyHint=true, and the description adds meaningful behavior beyond it: pagination semantics, the `name` fallback chain (operator-set → site brand → niche name), the distinction of niche.name as metadata, and the precise definition of lastActivityAt ('most recent change to the project or any of its content pieces'). No contradiction with annotations.

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

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

Three sentences, each earning its place: purpose and scope are front-loaded first, then two agent-critical disambiguation rules. Dense but not bloated — no filler or repetition of schema 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?

With no output schema, the description partially covers return semantics through name, niche.name, and lastActivityAt — exactly the fields an agent needs for project disambiguation. It lacks full return-shape and cursor-behavior detail, but for a read-only list tool with four parameters it is close to 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 low (25%, only `context` documented), so the description must compensate. It does map to the sorting.id enum (createdAt, niche, industry) and conveys pagination intent, but it leaves `cursor` mechanics entirely unexplained and adds nothing about the `context` parameter beyond the schema's own text.

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

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

States a specific verb ('List'), a precise resource ('all projects for the authenticated operator'), and scope modifiers ('paginated, sortable by createdAt, niche, or industry'). The disambiguation of `name` as the canonical project identity further separates it from siblings like get_project and create_project.

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 strong interpretation guidance: match operator references against `name`, and when the operator says 'my project' without naming one, select the highest lastActivityAt. This gives clear context for using the tool's output, though it does not explicitly name exclusions or alternatives such as get_project for a single named project.

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

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

Beyond the readOnlyHint annotation, the description discloses useful behavior: the returned snapshot includes per-topic index and article-suggestion counts, and it returns null when no radar snapshot exists. This is meaningful operational information an agent could not infer from annotations alone.

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

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

Two tightly packed sentences deliver the core purpose, return value, null behavior, and the onward path to expand_radar_topic. Every clause carries information with 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?

With no output schema, the description adequately explains what the return value contains, including the null case. It also places the tool within the larger radar workflow, making it fully usable by 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?

Schema coverage is 50%: context is documented in the schema, while projectId is not. The description reinforces that this is 'for a project' but does not add extra detail about either parameter beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List the latest emergent-topic radar snapshot for a project' and enumerates the returned topic fields. It also distinguishes itself from expand_radar_topic by explicitly naming that tool for the next step.

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: this is the read-only listing of a project's radar snapshot, and it explicitly points to expand_radar_topic for turning a topic into angles. It lacks explicit when-not-to-use or exclusions, but the sibling routing is strong.

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

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

Annotations declare destructiveHint=true, and the description greatly expands on this by naming concrete side effects: immediate IndexNow ping, ledger write, Passport stamp, and the wasted-ping consequence of calling it with a dead URL. It also reveals the downstream Search Console tracking dependency on recording a URL. This goes well beyond the structured 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?

Despite being long, every sentence carries operationally relevant information: behavior, prerequisites, exclusions, alternatives, and parameter semantics. The main action is front-loaded, and the detailed warnings and routing rules are placed exactly where an agent needs them. No filler or redundant restatement of the title or schema.

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?

This is a complex mutation tool with no output schema and minimal schema descriptions, yet the description covers purpose, side effects, timing, prerequisites, when not to use it, alternatives, and the meaning of the tricky publishedAt parameter. An agent has everything needed to decide whether 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?

Schema description coverage is only 25%, so the description carries most of the parameter meaning. It thoroughly explains publishedAt (ISO datetime, not in future, used for backdated go-live moments) and publishedUrl (must resolve, used for corrected/missing URLs). The id parameter is only implied as the suggestion identifier, and context is already described in the schema. This is strong compensation for the low schema coverage, though a small explicit mention of id would make it complete.

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: 'Record that an article went live at a URL.' It then enumerates concrete effects (flips suggestion to published, writes ledger, stamps Passport, pings IndexNow) and explicitly contrasts itself with update_article_status, so an agent can distinguish it from its closest sibling without inspecting schemas.

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

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

The description gives explicit when-to-use guidance: 'Call it only once the URL actually resolves,' 'Use this instead of update_article_status for the published transition,' and it explains why a status flip alone is insufficient. It also provides an alternative path for CMS-scheduled articles via update_article_status, making the decision boundary crystal 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?

Goes well beyond the minimal annotations by explaining that the tool appends a distribution-ledger row, that every registration is kept, and that derivative rows never affect publish status or Search Console attribution. This is exactly the kind of side-effect disclosure an agent needs.

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 earns its place: purpose, examples, ledger behavior, repeat registrations, scheduling semantics, and non-effects are all covered without filler. The length is justified by the amount of context necessary.

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 output schema, the description tells the agent how derivatives are surfaced later through get_article_suggestion and clarifies all behavioral side effects. It does not state the immediate return value, but the read-back path compensates well for a register-style 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?

With schema description coverage at only 17%, the description compensates by enumerating exact channel values, explaining scheduledFor as display-only from an external scheduler, and describing the relationship to suggestionId via the article suggestion. It does not fully enumerate all kind values (omits 'other') or explicitly define URL semantics, but most parameters are meaningfully 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?

States a specific action ('Register a derived asset') and ties it to an article suggestion, listing concrete derivative types. It distinguishes itself from siblings by noting what it is not — the article's own publishing state is handled by mark_article_published.

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 names the alternative for the article itself ('use mark_article_published for the article itself') and explains the registration workflow, including repeat posts on the same channel. It also sets a clear boundary: scheduledFor is display-only and VarynForge never posts on your behalf.

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

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

Beyond the annotations, the description discloses per-site rate limiting and the cooldown error message behavior. It does not detail exactly what destructive changes occur, but destructiveHint=true already signals mutation risk, and "refresh its owned pages" conveys overwrite 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 sentences front-load the action and trigger condition, then add the rate-limit caveat. Every sentence earns its place with no redundant restatement of the title or schema.

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 two-parameter, no-output-schema mutation tool, it covers the trigger, the action, and the relevant error behavior. It does not state the success return or whether the crawl is asynchronous, but those are minor gaps for this simplicity level.

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 describes context well and projectId is a conventional identifier, so the 50% coverage is not severely misleading. The description itself adds no parameter-level meaning, leaving projectId implicit, but an agent can reasonably infer it from the get_project_asset trigger.

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 clear action: "Re-crawl the project website and refresh its owned pages." It names a specific trigger via get_project_asset's mappingStatus, but it doesn't explicitly contrast with similar-seeming siblings like resync_asset_profile, so it stops short of full differentiation.

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 use conditions: when get_project_asset shows mappingStatus "error" or owned pages look stale. It does not describe when not to use it or point to alternatives, but the stated context is enough to route an agent correctly.

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

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

Beyond the destructiveHint annotation, the description discloses substantial behavior: overwriting profile facts, preserving unsupported fields rather than nulling them, stamping profileSyncedAt, leaving the niche untouched, and rate-limiting with a wait-time error. This is far more than the annotation alone provides.

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

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

The description is dense but efficient: action first, then trigger/usage, then side effects, then rate-limit behavior. Every sentence adds information and none is redundant with the schema or annotations.

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

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

For a two-parameter tool with no output schema, the description covers inputs, effects, edge behavior, and error conditions well. The only minor gap is that it does not state what a successful call returns, but the side effects and trigger context are sufficiently clear for an agent to proceed.

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 only 50%: context is described but projectId is not. The description does not add parameter-level meaning; it references 'the project website' but never maps that to projectId, and the context parameter's schema description already covers its semantics. It fails to compensate for the undocumented projectId.

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 ('re-read', 're-infer') and a concrete resource ('asset profile'), and enumerates exactly which fields are inferred. It also implies differentiation from the sibling update_asset_profile by focusing on website re-inference rather than manual editing.

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 trigger condition: use before rendering a report when get_pitch_report_payload flags assetProfile.syncedBeforeRun, because facts may have drifted. It does not explicitly name alternatives like update_asset_profile or state when-not-to-use scenarios, though it does clarify that the niche is not touched.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, which is thin. The description adds crucial expectations: feedback is not a ticket, no reply is produced, fixes must not be promised, and entitlement-wall payloads are working as designed. These behavioral details are not visible in the annotations or schema.

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

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

The description is long but every sentence earns its place: it front-loads the core purpose, then covers when-to-use, what kind to file, exclusions, the no-promise policy, and the follow-up path. No filler or 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 six-parameter tool with no output schema and minimal annotations, the description supplies the missing operational envelope: no reply, how to verify outcomes later via get_changelog, and what not to submit. It leaves some parameter-level specifics to the schema but fully covers selection, invocation, and post-call 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 only 17% (only context is described), so the description carries the burden. It adds real meaning for kind by naming the four values and specifying when missing_capability should be used, but it does not explain summary, detail, projectId, or toolContext beyond what the schema shows. Partial compensation for a large gap.

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

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

States a specific action ('File a note to the VarynForge team') and enumerates the four accepted kinds (bug, missing capability, friction, idea). The 'never a ticket / no reply' distinction differentiates it from support or inquiry tools, so an agent can identify its role without opening the schema.

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

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

Gives explicit when-to-call triggers ('something VarynForge cannot do', 'confusing tool result', 'frustration or a wish') and an explicit when-not-to-call exclusion (entitlement walls). It also tells the agent to prefer missing_capability over workarounds and points to get_changelog for follow-up.

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

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

The description goes well beyond the annotations by disclosing the 1.25× score boost, the 0-100 normalization side effect, the possibility of relative ranking drops, the pointer to rawOpportunityScore for verification, and the hiding behavior of 'ignored.' This is rich, non-obvious 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?

Three sentences, each carrying necessary information: the action, the scoring mechanics, and the hiding behavior. The most important information is front-loaded 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?

For a mutating tool with a required enum and important side effects, the description is broadly complete: it explains consequences, offers a cross-check path, and defines the ignored state. It could slightly improve by explicitly naming the 'default' behavior, but this is a minor gap.

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

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

The description clarifies the importance enum by explaining what 'important' and 'ignored' do, but it does not explicitly map companyId to the competitor or projectId to the containing project. With schema description coverage at only 25%, more semantic coverage of the ID parameters would have strengthened this.

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 precise verb and object: 'Mark a competitor important, default, or ignored.' It then explains what each state does, making the tool's purpose concrete and distinct from relatives 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 effects of 'important' and 'ignored' give useful contextual guidance for when this tool is appropriate, but it does not explicitly contrast with siblings such as add_competitor_by_domain or state when not to use it. The usage context is implied rather than stated.

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

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

Beyond the destructiveHint annotation, the description reveals the full behavioral profile: replacing the entire list, clearing via [], down-weighting in opportunity scoring, dropping from content-plan harvest, and persistence across research re-runs. It also explains the practical impact ('before results reach the operator'), which is exactly the kind of behavioral context an agent needs.

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 tightly written sentences deliver definition, examples, effect, destructive behavior, clearing semantics, and persistence. Every sentence adds distinct value and the most important 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?

For a destructive state-changing tool with no output schema, this description is complete: it explains what the tool does, how it behaves, what the destructive semantics are, and how to clear the list. An agent has everything needed to decide whether to invoke it and what arguments to pass.

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 only 33% schema description coverage, the description compensates well for the most important parameter 'terms' by explaining its meaning, giving examples, and documenting [] as a valid clearing value. It doesn't address projectId or context, but projectId is self-evident and context already has a clear schema description, so the gap is minor.

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 names a specific action ('Set'), a specific resource ('project-level exclusion terms'), and explains what those terms mean with concrete examples. It clearly defines the tool's scope and effect, making it easy to distinguish from other project configuration tools even without opening the schema.

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

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

The description gives clear context: use this for project-level exclusions when the operator explicitly does not sell certain products/topics, and notes it survives research re-runs. It contrasts with per-cluster dismissal, though it doesn't name a specific sibling tool or give an explicit when-not-to-use instruction, so it falls just 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?

Annotations only supply destructiveHint=true and readOnlyHint=false. The description adds important behavioral detail: dismissal hides from specific tools, is reversible via status=default, lasts only until the next research run, and changes normalization of all remaining clusters. This goes well beyond the annotation hints.

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

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

Four sentences, each carrying substantive information: the action, the affected surfaces, the persistence boundary with an alternative, and the normalization side effect. No filler or repetition of schema 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?

For a mutating tool with no output schema, the description covers what the tool does, when to use it, when to use an alternative, how long effects last, and what side effects occur. An agent has enough 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?

Schema coverage is only 25%, but the description compensates for the crucial status parameter by explaining what each enum value does. It also implicitly clarifies clusterId as the opportunity cluster being dismissed or restored. The context parameter is already well explained in the schema, and projectId/clusterId are standard UUID identifiers.

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?

Description opens with a specific verb and resource: 'Dismiss or restore an opportunity cluster.' It then clarifies the two status values and their visibility effects, making the tool's purpose unambiguous and distinguishable from siblings like 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?

The description explicitly names set_excluded_terms as the durable alternative for 'not my product' signals, and states that dismissal is temporary until the next research run. It also names the affected surfaces (list_opportunities and create_content_plan_from_opportunities), giving clear context for when this tool is appropriate.

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

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

Annotations already declare destructiveHint=true, so the description is not required to restate that this mutates state. It adds value by disclosing the downstream effect on the pitch report sequence and the read-back path via get_project.postsPerWeek, which helps the agent understand consequences beyond the mutation itself.

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 with no filler: the first states the core action and range, the second gives the effect and read-back mechanism. The most important information is front-loaded and 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?

For a simple three-parameter mutation with no output schema, the description gives the operation, the domain-specific range, the downstream impact, and how to verify the value afterward. The main missing piece is more explicit usage guidance, but the tool is simple enough that an agent can act on this definition.

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

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

Schema description coverage is only 33%, so the description should compensate for the undocumented parameters. It clarifies postsPerWeek's 'actual publishing' semantics and range, but gives no added guidance for projectId or context; context is left entirely to the schema, and projectId is not addressed at all in the description.

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 precise verb and resource: setting the operator's actual articles-per-week (1-14), and immediately explains why it matters by saying it sizes the pitch report’s 90-day content sequence. It is clearly distinguishable from sibling setters like set_opportunity_status or 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?

The phrase 'actually publishes' implies this is for the operator's real cadence rather than a target or plan, and the 90-day sequence consequence gives useful context. It stops short of explicitly saying when not to use it or naming alternatives, but the intended context is fairly 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?

Beyond the destructiveHint annotation, the description discloses that the action consumes one credit, returns async progress via runId, and behaves differently on the free plan by returning an entitlement instead. This gives the agent a clear picture of side effects and plan-dependent 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?

Three concise sentences front-load the action and outcome, then cover credit cost, return shape, and plan variation. Every sentence adds distinct information with no repetition of the title or schema.

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 two-parameter tool, the description covers purpose, side effects, return contract, async polling, and a plan-dependent exception. The only notable gap is the semantics of the id parameter, which is not explicitly stated as the project ID, so an agent may have to infer it from 'for a project'.

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 documents only context with a description; id has only type/format. The tool description adds the hint that the run is 'for a project', which implies id is a project identifier, but it does not explicitly define id or explain how context should be phrased beyond the schema's own description. This is partial compensation for the 50% 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 uses a specific verb ('Start') and resource ('research run for a project'), and enumerates the concrete sub-actions (discovers keywords, evaluates competitors, writes opportunity clusters). It is clearly distinguishable from siblings like get_research_status by stating the run starts and returns a runId to poll.

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 clearly implies the usage context: at the beginning of a research workflow. It also routes to get_research_status for progress, though it does not explicitly state when not to use this tool or mention alternative starting-point tools. The free-plan entitlement note adds a conditional branch but is more behavioral than usage-bound.

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

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

Annotations already mark this as destructive and non-read-only, and the description adds behavioral context: setting status to published here records no URL, scheduledFor holds the stalled-at-ready_to_publish flag, and publish auto-detect attests the live URL and pings IndexNow. It does not contradict the annotations and provides meaningful side-effect detail.

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 front-loaded with the core purpose, then covers edge-case transitions and scheduling. It earns its length because each detail prevents a costly wrong invocation, though it could be tightened slightly.

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 output schema, the description covers the critical decision points: which sibling to use, what happens with scheduledFor, and what the published status lacks. It does not describe the return value or error behavior, but those are less essential given the rich operational guidance.

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 only 20%, so the description bears a heavy burden for parameter meaning. It substantially clarifies status and scheduledFor semantics, but does not add meaning for id, context, or lastActor beyond what the schema enum/pattern already exposes.

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 ('Move an article through the production pipeline') and enumerates the full status enum, making the tool's function immediately clear. It also differentiates itself from the sibling mark_article_published by explicitly routing the published transition elsewhere.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use mark_article_published for the published transition, and do NOT call it before the URL is live. It also explains when to pass scheduledFor, clearly separating scheduling behavior from publishing behavior.

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

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

Annotations already indicate destructiveHint=true, and the description adds meaningful behavioral detail beyond that: only passed fields are written, arrays replace entire lists, no re-crawl occurs, and the profileStaleAt flag is cleared. This gives the agent a clear model of side effects and partial-update semantics.

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 tight sentences front-load the core purpose, followed by trigger condition and side-effect notes. Every sentence adds distinct value with no repetition or 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?

The description is complete for a mutating update tool: it states when to use it, what fields it affects, how partial updates and arrays behave, and side effects on re-crawl and the stale flag. The destructive nature is already covered by annotations, and no output schema exists, so return details need not be explained.

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 low (14%), and the description compensates by listing the semantic fields (description, primary offer, benefits, key differentiators, use cases) and clarifying array replacement behavior. The context parameter is not explained in the description, but the schema does describe it, mitigating the gap.

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

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

Description states a specific verb ('Correct') and resource ('the inferred profile of the project asset'), enumerating the fields involved. It also distinguishes itself from related flows by explicitly noting 'No re-crawl happens,' which contrasts with resync_asset_profile.

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?

Description gives an explicit trigger: use when get_project_asset shows claims contradicting what the operator sells (profileStaleAt set or operator says so). It does not explicitly name resync_asset_profile as the alternative for a full re-crawl, but the 'No re-crawl happens' note implies that distinction.

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

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

Annotations already flag this as destructive (destructiveHint: true) and not read-only, so the description doesn't need to re-state mutation. It adds valuable behavioral detail beyond the annotations: 'omitted fields keep their current values,' indicating a patch-style update rather than full replacement. This helps an agent understand the tool's safety profile without contradicting the annotations.

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

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

The description is two sentences with no filler. It front-loads the action and resource, then gives usage timing and partial-update semantics. Every sentence contributes actionable information for the agent.

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

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

For a destructive update tool with 9 parameters and no output schema, the description covers the key operational facts: what is updated, when to use it, and how omitted fields behave. It doesn't describe return values or explicitly warn about destructive consequences, but the annotations cover the destructive flag and the schema covers the required context parameter, so the description is reasonably 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 only 11%, so the description carries significant responsibility for parameter meaning. It lists most field names and explains that omitted fields retain current values, which is useful. However, it does not describe the required 'context' parameter or add meaning to ambiguous fields beyond their names; it compensates only partially for the 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 states a specific verb ('Update'), the resource ('niche profile'), and enumerates the exact fields involved (name, industry, language, country, target customer, core problem, related terms). This clearly distinguishes it from sibling tools like update_asset_profile or update_article_status by naming the niche resource explicitly.

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 trigger for use: 'Use after the operator refines their market definition.' It also clarifies partial-update behavior with 'omitted fields keep their current values.' It does not explicitly mention when not to use it or name alternatives, but the context is specific enough for an agent to select it appropriately.

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