VarynForge

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but no detail on side effects. The description adds meaningful behavioral context: it stores provenance verbatim, 'lands the suggestion in generating_brief', and 'forges its brief automatically' – explaining the side effects beyond the annotation. It also disclosure free-tier queue behavior. This goes beyond the annotations, adding valuable transparency about what happens in the system state.

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: the action + provenance, the state transitions, and the return value. Front-loaded with the verb and resource, 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?

Given the tool's complexity – it has side effects, workflows, and queue behavior – the description covers the purpose, usage context, side effects, and return value. However, it doesn't explicitly describe what happens to the idea if the daily cap is exceeded (does it still store provenance? is it queued immediately?), and it doesn't mention any prerequisites beyond 'from expand_idea'. With 9 parameters, it could clarify which optional ones matter, but the return type (suggestionId) is clear. Overall, strong but with small gaps.

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

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

Schema description coverage is 0%, but the description references the parameters conceptually: it mentions the idea (ideaText), title, angle, and searchIntent as inputs to the committed suggestion. However, it doesn't explain the meaning of optional parameters like nicheFit, demandEstimate, relatedQueries, reasoning – those are left to the schema's type definitions. Given 0% coverage, the description partially compensates but not fully, so a 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 states a specific verb ('Commit'), resource ('an expanded idea'), and outcome ('brief-ready article suggestion'), and explicitly references the upstream expand_idea workflow. This clearly distinguishes it from siblings like add_article_suggestion or create_article_suggestion_with_input, which likely handle direct creation rather than committing an expanded idea with provenance.

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 the tool is the next step after expand_idea ('from expand_idea') and notes the free-tier queue behavior ('queues past the daily cap'). It doesn't explicitly state when NOT to use it or name alternative tools for direct creation, but the context is clear enough for an agent following a workflow. A small deduction for not stating exclusions explicitly.

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 the tool is mutating (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description adds scoping context by calling it 'bare' and noting it only takes title plus optional intent and reasoning. However, it does not disclose details like whether existing suggestions are duplicated, what validation happens, or any expected side effects beyond adding a suggestion. This adds some value over the annotations but leaves room for more.

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 exactly two sentences, with zero filler or redundancy. The core behavior is front-loaded, followed by the alternative routing. 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?

The tool is a moderately complex mutation with five parameters, no output schema, and only about half the parameters explained in the description. The description clearly covers the difference from its main sibling, but does not explain the two required ID parameters or what the response looks like. For a tool that creates a record, an agent would benefit from even a basic statement of return behavior, which 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?

Input schema has no descriptions for any parameter, so the description must compensate. It names title, intent, and reasoning, which helps, but it omits the two required identifiers: contentPlanId and projectId. Their purpose is partially inferable from the phrase 'to a content plan' and their names, but there is no explicit guidance about why projectId is needed or how these relate. Three of five parameters are mentioned, leaving an incomplete and partially confusing picture for the agent.

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 is specific: 'Add a bare article suggestion to a content plan (title + optional intent and reasoning).' It names the exact verb, resource, and scope, and explicitly contrasts itself with create_article_suggestion_with_input, making the distinction from a key sibling clear. An agent can tell exactly where this tool fits.

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 says 'For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.' This names the alternative and defines the condition for selecting it. The 'bare' framing also implies when this tool is appropriate, giving an agent an effective decision rule.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which suggests this is a mutation but not destructive (maybe it's creation, which is neither read-only nor destructive). The description says 'Add' and 'Marks... on creation', so it's clear it's a write operation. It doesn't disclose anything about side effects like whether duplicate domains are rejected or whether it updates existing entries. Since annotations don't cover behavioral nuances, the description carries more burden, but it does state the creation and marking of importance. It doesn't describe what happens if the domain already exists, so a bit of a gap. Not a 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 two sentences, concise and to the point. It includes an example for the domain which is helpful. It's front-loaded with the primary action. No fluff. Slightly better than minimal.

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

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

Given the tool has 3 required parameters, all covered by name in the description, and no output schema, the description is relatively complete. It tells you what it does and the importance setting. But it doesn't mention what the response is (like success message or created object). It doesn't mention error conditions. For a simple creation tool, this might be enough, but there's room for more, like whether it returns the created competitor or just a status. However, many tools don't describe responses. I'd give 3.

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

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

Schema description coverage is 0%, so the description must compensate. The description mentions 'project by domain' and 'important or ignored', which maps to projectId, domain, and importance parameters. It gives an example domain format in the text, which helps. The importance parameter has an enum in schema, so values are known. But it doesn't explain what each parameter precisely means (e.g., projectId is a UUID, domain format). The description adds some semantic meaning beyond the schema (like the purpose of importance), but not much beyond that. So I'd say 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 states a specific verb ('Add') and resource ('competitor to a project by domain'), and includes an example domain. It also adds an elaboration on marking importance, which is distinct from the sibling 'set_competitor_importance'. However, it doesn't explicitly name a sibling or differentiate beyond that, so it doesn't fully distinguish from 'list_competitors' or 'set_competitor_importance', but it's clear enough.

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

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

The description implies usage: 'Add a competitor to a project by domain' and the importance flag. It doesn't explicitly state when to use this vs 'set_competitor_importance' or when not to use it. No alternatives or exclusions are mentioned. There's no mention of prerequisites (e.g., project must exist, domain must be valid). So it's adequate but lacks explicit 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=false and destructiveHint=false, the description goes beyond by revealing side effects ('this shapes where briefs, drafts, and lint formats anchor'), the confirmation requirement with the operator, and state-specific name handling. This adds meaningful behavioral context that annotations can't convey, only slightly short of 5 for not detailing error or reject 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?

A dense but efficient single paragraph. The contrast structure ('for X vs. for Y') earns its place, and the parenthetical showing naming conventions is high-value. Slightly long due to overlapping mentions of the UI, but each sentence adds operational information — strong but not minimalist.

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 simple parameters and no output schema, the description covers the essential complexity (the detected/planned state machine) completely. The mention of the operator-confirmation step and the 10-item limit round out the picture. Minor omission of the 'open' state and reliance on the UI for management keep it just shy of 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?

With 0% schema coverage, the description had to compensate — and it does, richly explaining type semantics (website vs. social handle naming conventions), and the two main state values. However, it omits the 'open' state enum value and doesn't address projectId at all, leaving minor gaps in an otherwise strong parameter walkthrough.

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+object pair ('Add a destination to a project') and immediately scopes it with 'where the operator publishes.' The two-mode behavior (detected vs. planned) is clearly the tool's distinguishing feature. It doesn't explicitly contrast against a sibling like list_destinations, keeping it from a 5, but the core purpose is unmistakable.

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

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

Excellent when-to-use guidance via the detected/planned distinction: 'for a destination that already exists' vs. 'one they intend to build.' It also conveys the 10-destination limit and directs the user to the web UI for management. Deduction for not naming a specific tool-based alternative, though the operational context is thorough.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It discloses important side effects: auto-creates the content plan when none exists, each suggestion lands in generating_brief, briefs forge automatically, and free-tier queue/forge-at-reset behavior. This is rich behavioral context, though it doesn't detail what happens on partial failures or how suggestionIds are returned (though it mentions they are returned).

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 but purposeful sentences. Critical preconditions and warnings are front-loaded, and every clause earns its place (duplicate handling, provenance, free-tier behavior). No fluff.

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

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

Given complexity (5 params, 4 required), minimal annotations, and no output schema, the description covers the workflow, side effects, and the return value. The only notable gap is the unexplained optional topicAngleTotal parameter and no explicit note on validation outcomes for invalid angles, but the coverage is strong overall for a complex tool.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains the relationship between signalObservationId and topicIndex (from list_radar_topics) and implies angles are the article suggestions. It doesn't explain the optional topicAngleTotal parameter, but the description still adds substantial meaning beyond the bare schema names for the key parameters.

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

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

The description states a specific action ('Add'), a specific resource ('selected angles from a radar topic' to 'the content plan'), and mentions provenance preservation and duplicate skipping, which distinguishes it from siblings like add_article_suggestion or create_article_suggestion_with_input. This is a clear verb+resource+scope definition.

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 preconditions ('call list_radar_topics first to get signalObservationId + topicIndex'), identifies the source tool for angles ('Angles come from expand_radar_topic'), and explicitly warns against a sibling ('do not also call generate_article_brief'). This proactively routes the agent and prevents misuse, going beyond mere 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?

Beyond the annotations (which only indicate false readOnly/destructive flags), the description discloses that it performs live searches (an external effect), consumes no credits but has daily/monthly caps, and conditionally omits opportunity score and cluster placement when no research run exists. This is crucial behavioral context that annotations alone cannot 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 efficiently organized: core purpose first, then usage guidance, then prerequisites, then exclusions. Every sentence adds essential information without redundancy. No fluff or filler.

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

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

The description covers the tool's purpose, usage context, prerequisites, exclusions, output behavior, cost implications, and conditional results. With no output schema, it adequately describes the return values (volume bands, ranking pages, and conditional opportunity score). There is nothing an agent needs to know that is missing.

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

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

The schema only defines two UUID parameters with no descriptions (0% coverage). While the description doesn't explicitly map parameter names, it clearly implies that suggestionId refers to the article idea under evaluation and projectId to the containing project. Given the low param count and obvious names, this implicit context is adequate, though explicit param explanations would earn a 5.

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

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

The description states a specific action (attach real search data to an existing article idea), the mechanism (one live Google search per target keyword), and the outputs (volume bands and ranking pages). It clearly distinguishes itself from siblings like start_research_run and create_article_suggestion_with_input, making its 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 explicitly states when to use the tool ('after create_article_suggestion_with_input, or on any existing suggestion...'), when not to use it ('Do not use to find new ideas or map a niche — that is start_research_run'), and the prerequisite for full output (a completed research run). This leaves no ambiguity for 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?

Annotations only establish that this is a non-read-only, non-destructive operation. The description adds meaningful behavioral detail beyond that: it auto-resolves a default content plan, creates/links search-query rows, returns specific IDs, and does not require a research run. This is useful side-effect disclosure consistent with the annotations.

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

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

Each of the three sentences earns its place: purpose, behavior and return values, then compatibility constraint. There is no filler, repetition, or schema duplication. The most important identification 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 9-parameter creation tool with no output schema and no per-parameter descriptions, the description gives core return fields and side effects but omits explanation of non-obvious parameters and product concepts like 'brief-ready' and 'default content plan'. It is enough for basic selection but not for confident invocation without further investigation.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining the 9 parameters. It references 'keywords' at a high level but provides no field-level semantics for angle, reasoning, searchIntent, targetAudience, wordCountTarget, or the required fields. The schema’s raw constraints are present, but the description does not compensate for the missing parameter documentation.

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

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

The description states a specific verb ('Create'), resource ('article suggestion'), and source ('from the operator's own input'), clearly distinguishing it from opportunity-driven or research-driven tools. It also names concrete outputs (suggestionId + contentPlanId) and the no-research constraint, leaving no ambiguity about what this tool does.

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

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

The phrase 'from the operator's own input' and 'Free-tier compatible (no research run required)' imply when this tool is appropriate, but the description never names sibling alternatives or states when not to use them. Usage context is present but left to inference rather than made explicit.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so it's not read-only, but the description doesn't disclose potential side effects like overwriting existing plans or creating duplicates. It does mention auto-creation of article suggestions, but lacks details on idempotency or confirmation requirements.

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

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

The description is a single dense paragraph that front-loads the core action and adds a parenthetical list of exclusions. It's concise but could benefit from bullet points for readability.

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 (harvesting logic, exclusions) and no output schema, the description is reasonably complete, but it doesn't mention response format, potential errors (e.g., if research isn't complete), or how the resulting plan is accessed. Those could be inferred from sibling tools.

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 one parameter (projectId) and 0% schema description coverage, the description doesn't explain the parameter at all. However, projectId is self-explanatory given the tool's purpose. The description mentions criteria like top-30 and exclusion thresholds, which add context beyond the schema but not parameter-specific semantics.

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

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

The description clearly states it creates a content plan by harvesting top-30 opportunity clusters and auto-creates article suggestions, distinguishing it from siblings like set_opportunity_status and set_excluded_terms which are referenced as excluded inputs.

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

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

It implies usage after a completed research run and explicitly mentions what is excluded, but does not explicitly state when not to use it or mention prerequisites like having a project with completed research. It could better contrast with sibling tools like list_opportunities or accept_idea.

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 readOnly=false and destructive=false. The description adds substantive behavior beyond that: the project is created asynchronously, projectId returns immediately, niche analysis and asset mapping run in the background, and callers should poll get_project until niche.analysisStatus is ready. This is valuable context not available from 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, each adding a distinct piece of necessary information: input options, async return, polling guidance, siteRelation handling, and organization default. It is dense and front-loaded with the core action, with no filler, though a bit of extra structure could make it easier to parse.

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 common path is well covered: what to pass, what happens after creation, how to poll, how to handle ownership ambiguity, and the organization default. But with 8 optional parameters, no output schema, and no explanation of the origin*/extras fields, the description is incomplete for non-website and alternative input scenarios.

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

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

Schema coverage is 0%, so the description carries the burden for parameter meaning. It explains website, nicheDescription, siteRelation (mine/client/prospect), and organizationId (defaults to personal organization). However, extras, originType, originInput, and originDescription are left undocumented, leaving nearly half of the parameters 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?

States the specific verb and resource ('Create a new project') and distinguishes it from siblings like get_project and list_projects by describing the creation action, input modes, and immediate return of a projectId. The purpose is unmistakable.

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

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

Provides clear context on when to pass a website URL vs. a niche description, when to set siteRelation, and when to pass organizationId with its default behavior. It also directs polling to get_project, but it does not explicitly name alternative creation paths or when-not-to-use exclusions.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable context by stating that the deletion cascades to the associated brief and keyword/cluster links, making the destructive scope concrete.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the cascade side-effect is stated immediately after. 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 single-parameter destructive tool with annotations covering the destructive nature, this description is complete enough. It explains the primary effect and the cascade behavior without needing an output schema or additional parameter 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 0%, so the description must compensate. It implies the single 'id' parameter is the article suggestion ID, but it does not explicitly state this or clarify relationships to the brief/keyword/cluster IDs. For one self-descriptive UUID parameter, 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 uses a specific verb ('Delete') and names the resource ('article suggestion') plus its associated brief. This clearly distinguishes it from sibling tools like add_article_suggestion, get_article_suggestion, and list_article_suggestions.

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

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

Usage is implied by the tool name and description: call when you need to remove an article suggestion. However, there is no explicit guidance about when to use this versus related tools, nor any exclusions or prerequisites.

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

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

The description adds meaningful behavioral context beyond the sparse annotations: the return is a single markdown string capped at ~8K chars, markdown-only, and structured fields are excluded. It does not address the readOnlyHint:false implication of possible side effects, but it does not explicitly contradict 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 compact at three sentences, with purpose front-loaded and usage/output details following in a logical order. Every sentence contributes distinct information, though it is slightly denser than 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?

The description covers the call pattern, output format, size cap, and the key sibling alternative, making it largely complete for a 4-parameter tool with no output schema. Minor gaps remain: it does not clarify why the schema enum also lists pdf and markdown, or whether any side effects exist given readOnlyHint:false.

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

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

With 0% schema description coverage, the description compensates by explaining format=markdown_inline and the channel parameter with its default. The IDs (suggestionId, projectId) are not described in prose, but they are standard UUIDs and referenced naturally as 'the suggestion’s per-channel briefs' and the project 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 clearly states the tool gets a brief as inline markdown to serve as a writing prompt, naming the specific format and resource. It also distinguishes itself from get_article_brief by explaining that structured fields are intentionally omitted, so the purpose is unambiguous and sibling differentiation is explicit.

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 direct usage instructions: pass format=markdown_inline and choose a channel with a stated default. It also tells the agent when not to use this tool by pointing to get_article_brief for structured fields, making the selection between alternatives 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 states 'without writing anything to the plan', which controls expectations about side effects beyond the raw readOnly/destructive hints. It also details the exact return values (title, angle, search intent, related queries, demand estimate, niche-fit score), which is valuable since there is no output schema. It could add error behavior or rate limits, but it provides solid 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?

Two tight sentences. The action is front-loaded, the core behavior 'without writing anything to the plan' appears prominently, and the return contract is listed efficiently. 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 tool with only two parameters and no output schema, the description covers what inputs mean, what results are produced, and how the tool fits the larger workflow (pass to accept_idea). It is complete enough for an agent to correctly invoke and interpret its result without needing additional documentation.

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

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

Schema description coverage is 0%, so the description bears the weight. It maps 'raw article idea' to ideaText and 'the project's niche' to projectId, giving meaningful semantics to both parameters. It does not restate string length limits or UUID format, but it makes the purpose of each parameter clear enough for an agent to call the tool correctly.

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

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

The description uses a specific verb ('Score') and a clear resource ('a raw article idea against the project's niche'), and immediately differentiates this from committing an idea by noting it does not write to the plan. It also names the concrete output (title, angle, search intent, related queries, demand estimate, 0-100 niche-fit score), leaving no doubt about what the tool does.

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

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

It explicitly says not to write anything to the plan and instructs to pass the returned fields to accept_idea to commit. This provides strong usage context and routes to the appropriate next step. A clear alternative ('check_idea') exists among siblings, but no direct comparison 'use this instead of check_idea' is given, so it stops just short of full 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?

The description goes beyond annotations by explaining the output behavior (near-duplicate flagging) and explicitly stating 'No writes', which complements the readOnlyHint=false annotation. It does not describe error handling or rate limits, but the annotations cover the basic safety profile, so the added context earns a high score.

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

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

The description is a single, well-structured sentence that packs essential information (input, output, optional parameter, and next step) without redundancy. The key details 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?

Despite lacking an output schema, the description explains the return format (3-6 angles with title, intent, editorial positioning) and the flagging behavior. It also provides the next step (add_radar_topic) and covers the main parameters, making the tool's behavior fully understandable for an agent.

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

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

The description references most parameters ('signalObservationId', 'topicIndex', 'customPov') and clarifies their roles (e.g., 'by signalObservationId + topicIndex' and 'Optionally pass customPov'). While projectId is not explicitly described, the description adds meaning beyond the raw schema and covers the core parameters.

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

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

The description clearly states the tool's verb ('Expand'), the resource ('radar topic'), and the specific output ('3-6 candidate article angles with title, intent, and editorial positioning'). It also indicates a distinct behavior (flagging near-duplicates) and distinguishes the tool from siblings like add_radar_topic by noting the follow-up 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 provides clear usage context: it explains the input parameters ('by signalObservationId + topicIndex'), the optional customPov, and explicitly notes that this tool does not write, guiding the agent to pass results to add_radar_topic. This effectively tells when to use this tool versus alternatives.

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

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

The description goes beyond the annotations (which only say readOnlyHint=false, destructiveHint=false) to disclose crucial behavioral traits: idempotency per channel, derivation from existing article briefs, the effect on daily slot consumption, and the return of '{ entitlement }' when the daily cap is reached. This transparency is essential for an agent to understand side effects and constraints, and it is accurately aligned with the annotations (it is a generative, non-destructive operation).

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

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

The description is moderately long but each sentence is purposeful, covering the core functionality, channel templates, derivation logic, idempotency, guidance usage, and free tier limits. It is front-loaded with the primary action, then details. It is dense but not verbose; it could be slightly shortened by removing some redundant qualifiers, but overall it earns a high score for structure.

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

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

Given the tool's moderate complexity (5 parameters, multiple channels, derivation logic, idempotency, entitlement), the description is remarkably complete. It covers all key behavioral aspects an agent needs to know: what channels exist, how they affect cost, when to use force and guidance, and what to expect on quota exhaustion. Since there is no output schema, the description explains the '{ entitlement }' return case. Nothing essential is missing 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?

In the absence of schema descriptions (0% coverage), the description compensates by explicitly explaining the 'channel' enum's possible values and their meaning. It also explains the semantics of 'force' and 'guidance' in context. However, it does not explicitly describe 'articleSuggestionId' and 'projectId' beyond their names, but their purpose is inferable from the tool's name and context. This is strong compensation, but a slight gap remains for the id parameters.

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

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

The description clearly states the tool's purpose: generating a writer-ready brief from an article suggestion, with a specific verb 'forge' and resource. It distinguishes itself from siblings by detailing how different channels produce different brief types (article, reels, youtube, x, linkedin), and by explaining the derivation logic and idempotency. This makes it unambiguous what the tool does and how it differs from, for example, get_article_brief or update_article_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 provides explicit guidance on when to use this tool: to generate a brief for a specific channel, with clear instructions on when to pass 'force' (to regenerate) and when to pass 'guidance' (when regenerating). It also explains the free tier limits and the behavior when the cap is reached. It implies when not to use it (e.g., when just fetching a brief, use get_article_brief) by describing generation vs retrieval. This is comprehensive usage 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?

The annotation readOnlyHint=true already signals a read-only operation. The description reinforces this by stating it is a read operation and adds transparency about shared caps and default org behavior, which is not covered by 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 overly verbose and repetitive. It lists the same items multiple times (e.g., plan/credits/limits, lint/draft caps) with redundant phrasings like 'the organization whose plan/credits/limits this payload describes' and 'its shared caps are the ones project actions consume.' It could be condensed to a few sentences without losing meaning.

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

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

Given the absence of an output schema, the description adequately enumerates the return fields and explains the reading context. It also mentions related tools (check_idea, lint_draft, list_organizations) for further actions, making it complete for an agent to decide when and how to call it.

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

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

The schema only provides a parameter name and type without any description. The description adds meaningful semantics: it explains the default (personal org) and when to override, plus the concept of shared caps. This is crucial for correct usage and fully compensates for the schema's lack of detail.

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

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

The description clearly states that the tool retrieves the operator account status, enumerating the specific data returned (plan, credits, quota state, lint/draft caps, locked tools, upgrade URL, next actions). It is distinct from sibling getter tools like get_project or get_draft_status, which target different resources.

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

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

The description gives explicit guidance on when to use the tool: 'Read on session start and after a wall hit.' It also explains the default behavior (personal organization) and when to pass organizationId, and references list_organizations for per-org details. It lacks explicit comparison to alternatives but provides sufficient 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?

Annotations only mark readOnlyHint=true, but the description adds substantial behavioral detail: which fields every brief carries, which fields are article-specific, the effect of compact, and the exact hasBrief/briefStatus/queuedUntil shape returned when a brief does not exist. It also explains the meaning of 'queued' and the daily-cap reset timing. This goes far beyond the structured annotations and is internally consistent.

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. The purpose is front-loaded first, then channel selection, then the payload fields, then the missing-brief status behavior. The description is information-dense but well-ordered, and none of it 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?

With no output schema, the description correctly takes on the burden of explaining return values: hookStatement, keyStats structure, always-populated fields, and the full missing-brief response. It also covers the unusual queue-forging state, which an agent would otherwise be unable to interpret. The description is complete for a retrieval tool with this parameter set.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for channel and compact: channel values are enumerated with 'article default' clarified and compact's effect on referenceArticles is stated. suggestionId is not explicitly described, but its role is clear from the opening sentence and the schema's UUID format. This is strong compensation, though not exhaustive for every parameter.

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

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

The description opens with a specific verb and resource: 'Get the full content brief for an article suggestion.' It clearly distinguishes this from siblings like generate_article_brief by framing itself as retrieval of an existing brief and detailing per-channel behavior. The description makes the tool's scope obvious without requiring 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 on how to use the tool: pass channel to select a channel brief, pass compact=true to drop referenceArticles, and poll after queuedUntil if the brief isn't ready. It does not explicitly name alternatives or exclusion cases, such as 'use generate_article_brief to create a missing brief,' so it falls short of a 5. Overall, an agent knows when and how to call this tool 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?

The annotations already declare readOnlyHint: true, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: the meaning of generating_brief with briefQueuedAt set (queued behind the daily cap, auto-forges at reset) versus null (actively forging). This is exactly the tribal knowledge — queueing, caps, state transitions — that an agent cannot infer from either the schema or 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?

Roughly 60 words with every sentence earning its place: purpose-and-scope in the first sentence, sibling routing in the second, and the densest operational knowledge (status semantics for the cap queue) in the third. Nothing is filler; the longest sentence carries the highest-information detail in the whole definition.

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 hint at return shape — it does, by naming the detail categories and their nesting (cluster context, derived asset types, keyword volumes). The only thing left out is the structure of the brief-availability field and edge-case return behavior, but the description correctly scopes those to get_article_brief. This is a defensible trade.

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

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

Schema coverage is 0%, so the description technically carries the disclosure burden, and suggestionId is never explicitly defined. However, with a single parameter whose name and strict UUID pattern make its semantics self-evident, the description's overall framing ('Get article suggestion details') makes clear the ID identifies the suggestion. The structural schema alone effectively documents this 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?

States a specific verb and resource ('Get article suggestion details') and concretely enumerates what's returned — metadata, cluster context, brief availability, derived assets (with examples), and target keywords. The description goes beyond the schema by naming the sibling it is not (get_article_brief) and by explaining the brief-status semantics, which is the single most important differentiation an agent needs.

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

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

Provides explicit routing: 'Call get_article_brief for the full brief' — giving the agent a clear trigger condition for the closest alternative. It doesn't explicitly discuss when not to use this tool relative to other siblings like list_article_suggestions, but for a single-ID getter with a tiny decision surface, the guidance covers the primary point of confusion.

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 indicates a safe read operation. The description adds behavioral context by specifying the output format ('plain markdown') and ordering ('newest first'). It doesn't contradict the annotation, and while it doesn't detail return value structure, it adds meaningful context about content and format 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?

Two sentences with no filler. The purpose is stated first, followed by concrete usage guidance. Every word adds value, and the description is tightly scoped to the tool's function.

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

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

For a zero-parameter, read-only tool without an output schema, the description is complete enough. It explains what the tool does, when to use it, and what format the output is in. The only minor gap is that it doesn't explicitly state what the URL points to beyond 'plain markdown', but this is sufficient given simplicity.

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

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

The tool has zero parameters, so the schema provides no parameter information. The description clarifies the return value is a URL to a markdown changelog, but since parameters don't exist, the description's value is in clarifying output semantics though it's not strictly parameter semantics. I'm considering the spirit: the description compensates for the lack of parameter schema by making the tool's purpose and output clear. However, the score aligns with the rule that 0 params yields a baseline of 4, and the description adds meaningful context beyond that.

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'), a specific resource ('URL of the VarynForge product changelog'), and clarifies the content ('what shipped, newest first, in plain markdown'). It clearly distinguishes itself from siblings by focusing on the changelog URL and its content format.

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 use it: 'Fetch it when the operator asks what is new'. It also provides a specific use case: 'in the days after a send_feedback report to check whether the gap they hit has been closed'. This gives clear contextual triggers and distinguishes from other get_* tools by focusing on changelog-specific scenarios.

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

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

Annotations declare readOnlyHint=true consistent with 'Get', a read operation, so there is no safety contradiction. The description adds value by disclosing what the response includes (domain, importance, SERP top pages, top keywords), which goes beyond the annotation. However, it doesn't address potential costs like enriched/rank data freshness or whether the response could be empty for new competitors, leaving some behavioral gaps.

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

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

A single sentence that front-loads the action and resource, then uses an em-dash to append return fields efficiently. No wasted words or repetition. Slight deduction because 'in a project context' is rather generic and contracts some meaning rather than expanding it, but overall deliberate and tight.

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 low-complexity tool (2 required ID params, no output schema, no nested objects), the description covers the essentials: what it gets, its scope, and what's in the response. Sibling ambiguity remains a gap—there are many 'get_*_detail' and list tools that overlap, and the description doesn't disambiguate. Given the minimal complexity, it's adequate but not thorough.

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

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

Schema description coverage is 0%, so the description carries the full burden of parameter explanation—but it never names companyId or projectId. The phrase 'in a project context' loosely hints at projectId, and the parameter names are self-explanatory, but nothing clarifies that companyId must belong to the project, what 'top pages' or 'top keywords' mean as return semantics, or the cardinality relationship between the two IDs. For 2 undocumented params, the description should at least gesture at the parameter relationship.

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

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

The description uses a specific verb ('Get'), a clear resource ('a competitor company detail'), and a scope qualifier ('in a project context'), then lists the included fields (domain, name, importance, top pages, top keywords). This clearly communicates the tool's purpose. It stops short of a 5 because it doesn't distinguish itself from similar siblings like list_competitors or get_keyword_detail by name—though the field list makes the 'detail' nature fairly clear.

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

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

There is no guidance on when to use this tool versus the many sibling tools. Nothing explains that list_competitors should be used to enumerate competitors first, or how this detail view differs from get_project, get_keyword_detail, or get_opportunity_detail. 'In a project context' reads as generic scoping language rather than a genuine usage rule.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. The description adds valuable behavioral context: the tool is free and uncapped, the status transitions are forward-only (a later flagged submission never demotes a suggestion), and the distinction between one suggestion status and N per-destination receipts. This goes beyond the annotation and helps the agent understand the tool's semantics. The only minor gap is not describing the exact response structure, but since there's no output schema, the description does a good job of explaining what will be returned (status, draft, gate receipt with verdict, per-check detail, thresholds).

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 well-structured. It front-loads the core purpose and the key usage directive ('always use this instead of lint_draft'), then explains parameter behavior, then the ownership model. Every sentence adds value. It's slightly long but justified given the complexity of the status model. The structure is logical: purpose, usage, parameter semantics, and model explanation.

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 (one status vs N receipts, forward-only transitions, per-destination details), the description is remarkably complete. It explains what the tool returns (status, draft, gate receipt with verdict, per-check detail, thresholds), when to use it, and the underlying model. There's no output schema, so the description carries the full burden, and it does so thoroughly. An agent could call this tool correctly without additional information.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains the `format` parameter's semantics (pass it to read one destination including stored draft text; omit for overview without draft bodies) and implies `suggestionId` is the identifier for the suggestion. The description adds meaning beyond the schema's bare type definitions. However, it doesn't explicitly describe the `suggestionId` parameter beyond the context, but the name is self-explanatory. Given the 0% coverage, this is a strong compensation.

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

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

The description clearly states the tool's purpose: to re-read an article suggestion's verification state without re-linting, providing the pipeline status and per-destination draft and gate receipt. It distinguishes itself from lint_draft by explicitly saying to use this instead of lint_draft to recover a known verdict. The verb 're-read' and resource 'article suggestion's verification state' are specific and 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 provides explicit usage guidance: 'always use this instead of lint_draft to recover a known verdict' and explains when to pass `format` (to read one destination including stored draft text) versus omit it (for per-destination overview without draft bodies). It also explains the status-ownership model, which helps the agent understand when to use this tool versus alternatives. This is exemplary 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?

The annotation readOnlyHint=true already establishes that this call is safe and non-mutating. The description adds useful content-scope context (the guide covers free/paid paths, token economy, walls/upgrade conventions) but does not mention response format, potential delays, or any further behavioral detail. Given the annotation coverage, the description adds moderate but not extensive behavioral transparency.

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 sentence, front-loaded with the action and resource, followed by a compact content list and a clear usage instruction. Every clause contributes value, with no filler or repetition of the tool name in a tautological way.

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

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

For a zero-parameter, read-only instruction-retrieval tool, this description fully covers what the agent needs: what it returns, why it matters, and when to invoke it. The absence of an output schema is not a gap here because the nature of the content is clearly described and the annotation confirms safety.

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

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

The tool has zero parameters, and the schema is effectively empty with 100% schema coverage. The baseline for a no-parameter tool is 4, and the description appropriately focuses on the resource and the reason to call it rather than inventing parameter guidance.

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: 'Get the VarynForge agent guide', and further clarifies what that guide contains (workflow paths, token-economy rules, conventions). This makes it clearly distinguishable in intent from sibling get_* tools like get_onboarding_guide or get_changelog, even though it does not name an alternative 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?

"Read this at session start" provides an explicit, actionable condition for when the tool should be used. It does not list alternatives or exclusions, but the temporal directive is strong and concrete enough for an agent to know this is the first-instruction retrieval step.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds value by disclosing the response contents (ranking pages, positions, ownership, related keywords), which goes beyond the annotation. However, it does not mention potential errors, rate limits, or pagination, but for a simple read operation this is acceptable.

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 identifies the resource and summarizes the output with no filler or unnecessary detail. Every word adds value.

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

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

For a simple read-only tool with two parameters and no output schema, the description provides a high-level summary of the return value. However, it omits parameter semantics and does not explain terms like 'ownership' or 'related keywords'. It is minimally adequate but could be improved by clarifying queryHash.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain what queryHash or projectId represent beyond their names. The tool name implies queryHash identifies the keyword, but this is not explicit. The description fails to clarify the parameters, leaving the agent to infer their purpose.

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 ('Get a keyword detail') and enumerates the returned data (pages ranking, positions, ownership, related keywords). This clearly distinguishes it from sibling detail tools like get_competitor_detail and get_opportunity_detail, and from list_keywords which would provide a list.

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

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

The description implies usage when keyword-specific detail is needed, but it does not explicitly contrast this with list_keywords or other alternatives, nor mention any exclusions (e.g., 'use list_keywords for an overview'). The guidance is inferred from the tool name and context rather than explicitly 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?

The readOnlyHint=true snapshot adds safety context, and the description adds further transparency by listing exactly what is read, how the rubric is structured, and how the channel parameter relies on the existing article default. There is no contradiction between the description and annotations.

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

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

The description is a dense two-sentence block: the first sentence defines the return value in detail, the second gives channel selection and timing guidance. It stays on-topic and each element earns its place, though the first sentence is long enough to be slightly more readable if split.

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 shoulders the duty of explaining what the rubric contains and how the channel parameter behaves. Combined with the schema's required suggestionId and channel enum, an agent has enough to call the tool correctly. The only meaningful gap is not explicitly flagging suggestionId as required.

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

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

Schema description coverage is 0 percent, so the description must compensate. It explains the channel parameter thoroughly — its enforce meaning and the requirement to match lint_draft — but suggestionId is only implied by the phrase 'for an article suggestion'. It does not explicitly state that suggestionId is required, leaving the schema to convey that detail.

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

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

The description opens with a precise verb-plus-object pair: 'Get the verification rubric for an article suggestion'. It then enumerates concrete contents of the rubric — submission format, required vs advisory checks, numeric limits (checkParams), and the brief fields read by lint_draft — making the tool's purpose unmistakable and distinct from siblings like lint_draft.

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 timing guidance ('Fetch this before writing so the draft passes on the first submission') and instructs the caller to pass the same channel they will pass to lint_draft. It doesn't name alternative tools to use in other scenarios, but the relationship to lint_draft clearly grounds 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 provide readOnlyHint=true, and the description aligns by focusing on diagnosis and returning data. It adds nontrivial behavioral context: the tool returns server-derived stage, a pitch, a checklist with statuses, and next_actions queue, and explicitly warns against a specific misuse. It doesn't contradict annotations, and the description adds substance beyond the annotation's minimal read-only hint.

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

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

The description is compact yet packed: purpose, trigger scenarios, alternative approach ('Diagnose before prescribing') and a direct warning. Every sentence serves a function, and the most important info (diagnosis, warning) is front-loaded.

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

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

Given no parameters, no output schema, and a readOnlyHint=true annotation, the description fully bridges the gap: it defines use cases, return fields, and the core rule (never welcome when producing). An agent can correctly invoke this without needing further explanation.

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 is empty (0 parameters) with 100% coverage by triviality, and the description explains that the tool requires nothing because it derives stage server-side. It adds meaning by explaining that no input is needed and what the tool infers (e.g., from list_projects emptiness), which is exactly what an agent needs to know when calling a parameterless tool.

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

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

The definition states a specific purpose ('Diagnose where the operator is in their VarynForge journey and get a guided setup path'), identifies clear trigger conditions ('call when...'), and distinguishes from siblings by referencing list_projects and warns against using the welcome pitch when 'producing'. This is distinct from the other get_* tools in the sibling list.

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 asks 'call when' scenarios and an exclusion ('never run the welcome pitch on an operator whose stage says producing'). This gives precise when-to-use and when-not-to-use guidance unlike most siblings.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds meaningful behavioral context about the output composition and flags the un-normalized nature of rawOpportunityScore, which is important for interpretation. It does not discuss error cases or output format, but the annotation lowers the burden.

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

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

The description is a single dense sentence that front-loads the operation and lists the exact return components without wasted words. Every clause contributes useful information, including the normalization caveat.

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 two simple required UUID parameters and no output schema, the description does a good job of explaining what the tool returns. It lists the major output categories and notes the score-normalization nuance, which is enough for an agent to invoke it correctly, though a more explicit statement of the projectId/clusterId relationship would make it fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining the parameters. It does not explicitly describe projectId or clusterId beyond what their names imply, and it never states which parameter identifies the cluster/opportunity. The names are readable, but the description adds no parameter-level meaning.

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

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

The description uses a specific verb ('Get') and identifies the exact resource ('cluster detail') while enumerating the concrete contents: top-20 keywords, top-10 ranked pages, top-5 competitor podium, article suggestions, and rawOpportunityScore. It also distinguishes itself from list_opportunities through the score-normalization note, 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 clear context by specifying what this tool returns and explicitly contrasts rawOpportunityScore with the normalized version returned by list_opportunities. It implies this is the tool for deeper single-cluster detail, though it does not state explicit when-not-to-use conditions or name other alternative getter 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?

Annotations include readOnlyHint=true, so the safety profile is established. The description adds value by disclosing that certain fields (headingOutline, targetKeywords, contentAnalysis) are conditional on the page being asset-mapped. This is beyond the annotations and helps set expectations for what an agent will receive. However, it doesn't disclose other potential behaviors like error cases or pagination, but given it's a read operation with conditional content, 4 is appropriate. 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?

The description is two sentences, concise and front-loaded with the main purpose. The conditional detail is placed after the core returns. It could arguably be split into three parts, but it's efficient. Loses a point because it could be structured with a hint about the conditional fields in a separate clause or list, but it's still well-organized.

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

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

For a read-only, 2-parameter tool with no output schema, the description covers the most important context: what it returns, and the condition under which certain fields appear. It doesn't explain nuances like dummy UUIDs (the pattern allows zero and all-f's) or what happens if the page isn't found, but those are minor. Given the tool's simplicity, the description is nearly complete. The conditional field population is the main gap, and it's addressed.

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

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

Schema description coverage is 0%, meaning the description adds no parameter-level meaning. The schema itself provides names (pageId, projectId) and UUID formats but no semantic hints. The description mentions that certain fields populate for owned pages but doesn't explain what pageId or projectId refer to beyond common sense. Since there are only 2 simple parameters and the description doesn't explicitly clarify them, but they are fairly self-evident, a baseline 3 is appropriate. It doesn't actively mislead, just isn't helpful.

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 ('Get') and specific resource ('page dossier') and enumerates what it returns: URL, title, project rankings, ownership. It also clarifies that some fields populate only for owned pages, which distinguishes it from generic page lookup tools. This clearly differentiates it from siblings like list_pages or get_project_asset.

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

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

The description implies usage: when you need a comprehensive dossier for a specific page, including ownership and optional analysis fields. It doesn't explicitly state when not to use it or name alternatives, but the richness of the returned fields suggests it is for deeper context rather than listing or asset retrieval. The condition about owned pages is a clear usage hint, though not explicit about alternatives. This is slightly below a 5 due to lack of explicit when-not 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?

The description discloses that the payload includes assetProfile, renderGuide, and conditions like 'syncedBeforeRun' and 'offer the operator the choice', which adds behavioral context. However, the excessive repetition and inclusion of rendering instructions (which are more about downstream usage than the tool's own behavior) dilute the transparency.

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 an extremely long, run-on sentence with repeated phrases like 'no search-volume numbers by design' and 'under the operator's name'. It is poorly structured and overly verbose, making it hard to parse. The key information could be conveyed in a few concise sentences.

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 numerous aspects: report structure, assetProfile, renderGuide, and conditions, making it fairly complete. However, the information is presented in a disorganized manner, and some elements (like rendering instructions) may be irrelevant to the API call itself, so completeness is achieved at the cost of clarity.

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, runId, is given meaningful context in the description ('Pass the runId from get_research_status'), which helps the agent source it correctly. This adds value beyond the bare schema requirement of a non-empty string.

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

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

The description clearly states the action: 'Assemble the pitch report payload' for a completed research run, which distinguishes it from other get_* tools. However, the verbosity obscures the primary purpose, making it less crisp than ideal.

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 says 'for a completed research run' and instructs to pass the runId from get_research_status, including handling for incomplete runs (returns null). This provides clear guidance on when to use it, though it stops short of naming alternative tools for other scenarios.

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

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

The annotation readOnlyHint: true covers the read-only nature. The description adds value by listing the fields returned, which informs the agent of the response shape. However, it does not describe error behavior, permissions, or any other side effects beyond the annotation, so transparency is only partially enhanced.

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 verbose and redundant. It spends words on clarifying field semantics ('operator-set, falling back...', 'Address the project by name; niche.name is the market niche...') that are not necessary for the tool's purpose. The structure is a single long sentence that could be split and simplified. This detracts from readability.

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 getter with one parameter, the description adequately explains the returned fields, which helps an agent interpret the response. However, it lacks usage guidance (when to call this vs list_projects) and does not mention any potential errors or prerequisites. The annotation provides read-only context, but the overall completeness is moderate.

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 fully defines projectId as a UUID with format and pattern. The description does not add any additional meaning to the parameter; it neither clarifies that projectId is the project's unique identifier nor provides any context about where to find it. Thus, the description contributes nothing beyond the schema.

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

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

The description clearly states that the tool retrieves a single project and enumerates the returned fields (canonical name, niche, audience, research status, postsPerWeek). The verb 'Get' is specific, and the tool is distinct from list_projects. However, it does not explicitly name the sibling list_projects as the alternative for fetching multiple projects, so it is not fully distinguished.

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 does not explicitly state when to use this tool versus alternatives like list_projects. It implies use when a single project's details are needed, but this is not stated. The agent must infer usage from the tool name and the sibling list, which is a gap.

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 already carry the readOnlyHint:true and there is no contradiction. The description adds value by exposing the shape of the returned data (URL, name, description, solution profile), which is meaningful contextual benefit beyond the annotation. However, it omits behavioral details like what happens for a project with no associated asset, whether an error or null is returned, or whether the 'solution profile' is a nested object.

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?

Exactly one sentence, zero filler. The core action is front-loaded ('Get the asset'), the disambiguator follows immediately, and the return fields are listed efficiently with em dashes. 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 low-complexity, single-parameter, read-only tool, the description is nearly sufficient: annotations signal safety, and the field list partially substitutes for a missing output schema. The notable gap is the unresolved edge case of a project with no asset — it's unclear whether that yields null, an empty object, or an error — which an agent would likely hit in practice.

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

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

Schema description coverage is 0%, so the description should compensate but does not directly address projectId at all. That said, there is only a single parameter whose self-documenting name and strict UUID pattern (including two sentinel zero/ones patterns) largely carry the meaning. The description's field list is about the return value, not the parameter, so the description adds no semantic detail about how projectId behaves or what valid values mean.

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 clear verb-resource pair: 'Get the asset ... associated with a project' and disambiguates the potentially vague term 'asset' with the parenthetical '(website/product)'. It goes further to enumerate the return contents ('URL, name, description, solution profile'), which pins down the tool's responsibility. It loses a point because, among the 59 siblings with many get_* tools (get_project, get_page_dossier, get_starting_point_report), the description doesn't fully clarify when this specific 'asset' resource is the right one to fetch.

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

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

No guidance is provided on when to call this tool versus its 58 siblings. There is no mention of alternatives, preconditions (e.g., must the project exist? must an asset first be created via 'resync_asset_profile' or 'register_derived_asset'?), or scenarios where this specific read is appropriate. Given the large sibling set, even a single sentence of routing context would meaningfully help.

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, and the description adds significant behavioral context beyond that: the sorting rules for topPriorities (priorityScore desc; radar-born suggestions rank oldest-first below scored ones), the null-handling semantics (source tells you why score/cluster may be null), and the status-based filtering for nextActions. It could have addressed empty/error states, but for a read-only overview tool this is genuinely helpful disclosure.

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

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

The description is dense but every clause earns its place — there is no filler or redundant verbiage. The key 'at-a-glance' concept is front-loaded, and all subsequent detail (sorting, statuses, source semantics) enriches the core message. The wall-of-text format with deeply nested parentheticals hurts scannability, but nothing is wasted.

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 complexity (four return components, no output schema, 60+ sibling tools), the description covers the nuanced behaviors an agent would need: what counts as 'next' work, the statuses that mean a piece still needs work, the ranking of scored vs. unscored suggestions, and why fields may be null. This is exactly the kind of edge-case decision logic that would otherwise cause an agent to misbehave. The absence of coverage for hypothetical edge cases (e.g., empty projects) is forgivable given the depth of the semantics 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?

With 0% schema description coverage and one parameter (projectId), the description does not explicitly document the parameter. However, the parameter name combined with the tool name makes its meaning self-evident, and the schema robustly documents the UUID format and pattern. The description could have added value by clarifying that projectId is the target project, but the risk of ambiguity is minimal.

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

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

The description opens with a specific verb+resource ('Get the at-a-glance read on a project') and enumerates the four components returned (niche summary, keyword stats, nextActions, topPriorities). This clearly differentiates it from siblings like get_project or get_article_suggestion without needing to open 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 provides an explicit trigger for when to use this tool ('offer its first entry when the operator asks "what now?"') and clarifies the meaning of 'done' vs. what constitutes actionable next work. It doesn't explicitly name alternatives or exclusion criteria, but the trigger phrase and the detailed semantics of what to do with the returned data offer strong situational 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 declare readOnlyHint=true, so the description doesn't need to restate that. It adds substantial behavioral context: the tool is token-light (returns a small fixed shape, no step payloads), and it explains the meaning of the retryable field and the stalled-run heuristic. The only minor gap is not describing pagination or rate limits, but for a single-project poller this is sufficient. The description adds value beyond the annotation without contradicting it.

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 well-structured: it front-loads the core purpose and return fields, then explains the failure diagnostics and the stalled-run heuristic, and ends with a token-light note. Every sentence adds value, and the structure guides the agent from what it returns to how to interpret it. No fluff or repetition.

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

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

For a read-only poller with a single parameter and no output schema, the description is complete. It covers the return shape, the failure diagnostics semantics, the retryable field's three states, and the stalled-run edge case. The agent has everything it needs to call the tool and interpret the result correctly. The readOnlyHint annotation covers the safety profile, and the description covers the behavioral nuances.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explicitly describe the projectId parameter, but the parameter is a simple UUID with a clear name and the description's context ('for a project') makes its purpose obvious. The description focuses on the return shape, which is the more complex part. Given the single simple parameter, the description provides adequate context, though it could have explicitly stated that projectId identifies the project whose latest run is polled.

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

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

The description clearly states the tool polls the latest research run for a project and lists the exact fields returned (runId, status, phase, progress, elapsed, failure diagnostics). It distinguishes itself from siblings like get_draft_status and get_account_status by focusing on research runs and their structured failure diagnostics.

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

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

The description explicitly tells the agent when to use it (polling a research run) and provides critical guidance on interpreting results: a running run with phase 'initializing' and large elapsedSeconds is stalled and should be reported rather than waited on. It also explains the retryable field semantics, telling the agent when retrying is safe and when to fix inputs or report. This is actionable usage guidance beyond mere description.

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

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

Annotations already provide readOnlyHint=true, and the description does not contradict that. It adds valuable context about what the report contains (client-facing, assembled from setup-time data), how lockedSections behaves (names sections absent until a research run), and the rendering options (markdown vs structured fields). While it doesn't discuss errors or performance, the behavioral profile is well-covered 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 longer than average but every sentence contributes: purpose first, then free/availability, then rendering details, then lockedSections, then the alternative. It is efficiently front-loaded with the core message and avoids redundant filler, though it could be trimmed slightly without losing key facts. Overall it is well-structured and information-dense.

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

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

For a getter tool with a single parameter and no output schema, the description is thorough: it explains the report's content, its availability, what lockedSections means, and how the rendered output differs from structured data. The only minor gap is the lack of an explicit note about response shape (e.g., whether the markdown is a string or a file), but the description's mention of 'ready-to-send render' sufficiently covers it. Given the simplicity of the tool, completeness is high.

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

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

Schema coverage is 0%—the lone parameter projectId has no description in the schema, and the tool description does not mention it at all. However, the schema itself provides a strict UUID format and pattern, making the parameter self-explanatory for a tool named 'get_starting_point_report'. Because the parameter is trivial and the schema is authoritative, the description's omission does not cause confusion, but it also adds no semantic value, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Get') and a precise resource ('the free starting-point report for a project'), then elaborates on what the report contains (positioning, site inventory, competitor set, rising-topic signals). It explicitly names the sibling tool (get_pitch_report_payload) and the condition that selects it ('prefer get_pitch_report_payload: that is the full report'), leaving no ambiguity about which tool to call.

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 states the tool is 'Free on every plan, no research run required,' and gives a clear when-not-to-use instruction: 'Once the project has a completed run, prefer get_pitch_report_payload: that is the full report.' This directly addresses when to use this tool versus the alternative, fulfilling the guidelines dimension completely.

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 the compactness behavior: FAQs cap at 6 and long sections degrade to fit a deep-link budget. It also reveals that deepLinks is null over MCP, a runtime behavior an agent would not otherwise know. This adds valuable context not covered by 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 concise and well structured: it opens with the core purpose, followed by limitations and alternatives, and ends with a specific field behavior. Every sentence adds value, and the most critical information (what it does) 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?

Although there is no output schema, the description adequately explains what the payload contains, its limitations, and directs users to full sources. It covers the single parameter implicitly, notes the deepLinks behavior, and is complete for a one-call read tool. An agent has enough to invoke it correctly and interpret the response.

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

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

The schema defines suggestionId with UUID format and pattern but no description. The tool description adds the context that it is 'for an article suggestion', clarifying the parameter's role. For a single well-named parameter, this is adequate but minimal—no additional details like how to obtain the ID or constraints beyond the format. Schema coverage is 0%, so the description does compensate partially but not thoroughly.

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

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

The description clearly states the tool 'returns a compact writing payload for an article suggestion', listing the specific contents (brief essentials, keywords, acceptance criteria, lint instructions). It also differentiates it from siblings by naming get_article_brief and get_lint_rubric as the full counterparts, so the purpose 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?

Explicitly states when to use this tool vs. alternatives: 'the FULL brief is get_article_brief and the full check list is get_lint_rubric, so verify against those, not this.' This gives clear guidance that this is for quick access and that the full sources must be consulted for complete information. Also notes the deepLinks field becomes null over MCP, setting expectations for use.

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 reveals important behavioral details beyond the readOnlyHint annotation: the prompt binds to the brief, acceptance rubric, and opportunity context fetched from the account, and 'degrades to generic writing advice without them.' It also discloses per-channel methodology, giving an agent a realistic model of what the prompt will contain.

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

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

The description is front-loaded with purpose, then behavioral context, then parameter guidance. It is dense but every sentence adds necessary information: what the tool does, how it behaves contextually, which channel values exist, and what each produces. There is 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?

With one enum parameter, a readOnly annotation, and no output schema, the description provides everything needed to call the tool correctly: the exact channel values, their meaning, the default, the expected behavior, and the fallback behavior. Returning a prompt is self-evident, so no return-format explanation is necessary.

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

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

Schema description coverage is 0%, so the description carries the full burden for the `channel` parameter. It lists all enum values, explains what each channel covers, and notes the default. This fully compensates for the schema's lack of parameter descriptions.

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

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

The description states a specific action ('Get the writer system prompt') and resource ('for drafting one content type from its brief'), and further differentiates the tool from siblings by spelling out that each channel has its own methodology. This is far more specific than the title alone and 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 explicitly instructs when to use the tool: 'Load the prompt for the channel you are about to draft' and states that article is the default. It also explains what each channel is for ('article covers voice adaptation... reels and youtube cover production script'). It does not name alternatives or explicitly say when not to use it, but the context is clear.

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

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

The description richly discloses side effects beyond the sparse annotations: pass moves status, flag moves to draft_ready, re-submission replaces same-format drafts, status transitions are forward-only, waived checks still run, and unchanged drafts are cached. These are exactly the behavioral details an agent needs and cannot infer from 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 information-dense and every clause adds operational value. It is front-loaded with the core purpose, though the dense single-block structure with multiple parentheticals could be easier to scan with bullets or section breaks.

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

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

For a tool with no output schema and high complexity, the description is complete: it explains return fields, thresholds behavior, channel-specific check limits location, storage semantics, quota handling, caching, and forward-only transitions. An agent can correctly select and invoke this tool without needing to open sibling tool schemas.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it pays off: it explains channel enum semantics and submission shapes, format storage/replacement rules, waiveChecks operator intent, and draft content expectations per channel. Even suggestionId is clarified as referring to the suggestion whose brief is being graded.

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 and resource: 'Submit a draft for verification against its brief' and states the pass/flag verdict outcome. It clearly distinguishes itself from sibling tools by framing linting as a draft gate tied to status transitions, not an idea/brief/research operation.

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 usage rules: always pass `channel` for non-article content, use `format` for grouping, never re-lint to recover a lost verdict, and consult get_draft_status for stored results. It also directs users to get_lint_rubric for numeric limits and get_account_status for the daily cap, making alternatives and exclusions explicit.

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

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

The readOnlyHint annotation already declares the tool safe, and the description adds substantial behavioral context beyond that: the per-channel distributions rollup shape, page-through behavior, and a nuanced status semantics (queued behind the daily cap vs actively forging, with advice to re-check within a minute). No contradiction with 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 front-loaded with the value proposition and return fields, then moves to pagination guidance and status semantics. It is longer than minimal, but every sentence adds necessary operational detail 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?

Given there is no output schema, the description carries the full burden of explaining the response shape, including the rollup object and status behaviors. It also covers pagination and alternates for full records and brief status, leaving little ambiguity for an agent deciding how to use the tool.

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

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

The schema has 0% description coverage, so the description carries most of the parameter-meaning burden. It does clarify the generating_brief status meaning and implies pagination with 'Page through suggestions,' but it does not explicitly explain projectId, limit, or cursor behavior, so coverage remains partial.

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 the exact returned fields (title, status, priority, cluster, intent, source, publishedAt, scheduledFor, and a per-channel distributions rollup). It also distinguishes itself from sibling get_article_suggestion by explicitly pointing to that tool for the full record.

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

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

The description gives explicit guidance: use the list to spot gaps 'without per-item reads' and 'call get_article_suggestion for the full record' when more detail is needed. It also routes status-related follow-ups to get_article_brief, naming the exact alternative and conditions clearly.

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 sorting order, cap at 100, and the importance bucket behavior. The description does not contradict annotations and adds detail about the output ordering and filtering, which is useful for the agent to predict behavior. It doesn't mention pagination or what happens if limit is exceeded, but annotations cover the read-only nature.

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 fluff. It front-loads the main purpose, then provides sorting, filtering, and cap details. Every sentence adds value and it is appropriately compact.

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 is a listing operation with 3 params and no output schema, the description covers the input usage, output ordering, and limits. It doesn't detail the return structure (fields per competitor) but that might be expected from the domain or not required. The annotations and description together are sufficient for an agent to call it correctly, though a note about default behavior without 'importance' could be clearer, but it's not a major gap.

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

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

Schema description coverage is 0%, so the description must explain parameters. The description explains 'importance' (filter to one bucket) and 'projectId' is implied as the project. It mentions the limit cap of 100 implicitly via 'Capped at 100' when limit is set. Without parameter-specific descriptions, the description compensates reasonably, but some parameters like 'limit' semantics are clear from schema, and the description adds the sorting context. It adds meaning beyond the schema, so a 4 is justified.

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

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

The description clearly states the tool lists companies for a project, distinguishes between marked (important/default/ignored) and unmarked (SERP-discovered) competitors, and specifies the sorting order and cap. This is specific to the 'list' verb plus resource, and the mention of importance filtering distinguishes it from sibling tools like get_competitor_detail and 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 conveys when to use it for listing competitors and explicitly mentions the optional 'importance' parameter for filtering. It implies this tool is for listing rather than modifying (which is done by set_competitor_importance) but does not name alternatives or when-not-to-use. The context of sorting and cap helps the agent decide if it suits the need.

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 include readOnlyHint=true, so the read-only nature is covered. The description goes beyond by disclosing the structure of rows (briefChannel, verifiable, publishable, publishVia) and their semantics, clarifying that it never requires cross-referencing other tools. This is valuable behavioral insight 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 dense but structured. It front-loads the core purpose and enumerations, then details field semantics. It could be slightly more concise (the field explanations are somewhat verbose), but every sentence adds practical value and no filler exists.

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

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

Given the tool's moderate complexity (single parameter, no output schema, no annotations beyond read-only), the description is robustly complete. It covers purpose, response structure, edge cases (empty list), and integration with other tools (publishVia, lint_draft). Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 0% — the description never mentions projectId, which is the only required parameter. With one simple UUID parameter and a rich description of the response semantics, the gap is minor but still present. The description compensates well for the output but not for the input parameter.

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

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

The description clearly states the tool lists project destinations for publishing, enumerates specific types (website, youtube_channel, tiktok, etc.), and is distinguishable from siblings like add_destination. The verb-resource pair 'list destinations' is precise and unambiguous.

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

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

Provides explicit guidance on when to use this tool (to see destinations, check capabilities) and what to do when returning an empty list (add a destination or fall back to brief channel name). However, it doesn't explicitly contrast with other list tools (e.g., list_article_suggestions), though the domain difference is implicit. The empty-list handling is a strong usage cue.

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 description rightly omits that. It adds behavior beyond annotations: pagination behavior, support for sorting and intent filter, and the volume bucket enum values. It does not contradict the read-only annotation and provides useful operational context.

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

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

The description is a single concise sentence that front-loads the core purpose and packs in field details, pagination, sorting, and filtering without any wasted words. It is appropriately sized and well-structured.

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

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

For a tool with 5 parameters including nested objects, no output schema, and no parameter descriptions, this description is insufficient. It omits critical details such as how cursor pagination works, how to construct the sorting array, and how volume bucket values relate to parameters or responses. The agent is left with too much inference required.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions that pagination, sorting, and intent filtering are supported without explaining cursor usage, sorting array structure, or the meaning of each parameter. It names the existence of these features but not how to use them, leaving the agent to guess from the schema structure alone.

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 keywords tracked for a project') and enumerates the returned fields (text, difficulty, intent, volume bucket with its enum values). This clearly differentiates it from sibling list_* tools like list_competitors or list_pages by the resource type.

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

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

The description implies usage for browsing a project's keywords and mentions pagination, sorting, and intent filtering, which gives some context. However, it does not explicitly name alternatives or state when not to use this tool (e.g., for a single keyword use get_keyword_detail). No exclusions are provided.

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 shoulders the entire behavioral burden since annotations expose only readOnlyHint=true, and it delivers: hidden-by-default coverage, the exact contrast between hidden vs. down-weighted clusters, the nuanced fitFlag semantics ('treat them as comparison-content candidates at best, never headline opportunities'), and the non-obvious normalizing side effect that 'coverage filtering, dismissing, excluding, or fit-flagging can shift the relative numbers of other clusters'. This last insight about score drift is exactly the kind of subtle behavior an agent could not infer from code or 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 unusually information-dense without being terse — every sentence earns its place. It leads with the one-sentence definition, then progresses deliberately through filters, state-driven exclusions, fit handling, and the normalization caveat. A wall of text, but skipping it would cost the agent genuine planning capability.

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 this complex — 7 parameters, 2 enums, cross-tool state coupling, relative scoring — the description addresses nearly every non-obvious behavior: defaults, hiding rules, score normalization, and fit-flagging semantics. Only minor gaps remain: the cursor pagination and activeMetaCluster filtering are never mentioned, and they aren't self-explanatory from names alone. The total 0.9 must be split across the 4 coefficients carefully, so 3.7 rounds to 4.

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

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

With 0% schema description coverage, the description carries full parameter documentation burden. It explains `goal` and `coverage` (including the hidden default ["gap","partial"] and the 'covered' opt-in semantics, which no schema-derived source could convey). Given the deliberately rich write-up of the goal and coverage parameters, a 4 is the right ceiling — it does not over-explain the already-inferable numeric parameters.

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

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

The opening sentence — 'List content opportunity clusters sorted by opportunity score' — is a model verb+resource statement that names exactly what the endpoint does and how output is ordered. It's clearly differentiated from siblings like get_opportunity_detail through the rich behavioral detail, though it never explicitly names the sibling it is not the way the top calibration example does.

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

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

The description references sibling mutations (set_opportunity_status, set_excluded_terms) and explains their causal effect on this list — dismissed clusters are hidden, excluded terms down-weight scores — which tells the agent precisely how this tool composes with its siblings. It also documents the default coverage behavior (["gap","partial"]) and the 'refresh candidates' workflow. It stops short of an explicit when-not-to-use or a pointer to get_opportunity_detail for drill-down needs, but the context is genuinely 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 minimal readOnlyHint: true annotation, the text carries significant behavioral weight, describing the return padding/ordering (the list includes pending invitations and per-organization limits) and the fact that this service side-effect-free. The inclusion of semantics such as mentions of the domain (plans, credits, and limits are scoped to an organization, a project belongs to exactly one organization) tells a calling agent the relevance context without calls. It doesn't reveal whether the list is empty or deterministically ordered, but it's a strong probe.

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 on the wordy side for a zero-parameter function: the field enumeration is good, but the second sentence mixes a domain note about the project↔organization relationship (which sits better near create_project) and carries a marginally related note about per-organization ratings. Trimming and reshaping would tighten the point, though the most pertinent details are still up front.

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 this endpoint has no parameters, no output schema, and no nested entities, the description sufficiently covers call/return semantics with in-text enums for roles. It points out the caveat about pending invitations and current next steps (create_project/get_account_status), making it fully callable by any agent. It doesn't spell out failure modes (e.g., authentication errors) or empty-list behavior, but it's nearly unimpeachable for a parameterless read.

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

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

There are no parameters to document (zero parameters, zero required). The textual description exhaustively covers the empty input contract; a neutral-high score of 4 is appropriate when there is nothing left to describe, while the text still enriches the model with the fields in play.

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 begins with a clear, specific action ('List the accounts this account belongs to'), followed by the exact set of fields returned (id, name, role with its enum values, is_personal, plan, member_count). This unambiguously distinguishes it from sibling list_* functions without leaving the reader guessing which object type is being enumerated. It is specific enough to select correctly.

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 describes handling the result (a pre-specifically-directed next step: 'Pass an organizationId to create_project... or get_account_status') and handles the edge case of pending invitations (which occur in the web app). It doesn't explicitly contrast with list_projects, but the field-level detail makes the boundary clear. It would be stronger with a direct 'This function does not require an organizationId.'

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, covering the safety profile. The description adds genuine behavioral value beyond that: 'ranked' signals a server-side default ordering behavior, and the field enumeration plus 'tracked for a project' scoping tells the agent what to expect in results. The only minor gap is no explicit statement about pagination, but annotations bear the core safety burden.

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, zero filler. The first clause states the core purpose, followed immediately by the highest-value semantic detail ('ranked'). The filtering note is a natural second clause. Every word earns its place, and the key differentiator ('ranked') 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 5-parameter tool with nested objects and no output schema, the description covers the essential semantics: what fields come back and how to filter. It doesn't explain sorting options or pagination, but those are discoverable from the schema's enum and structure. For this complexity level, the description is complete on the parts that aren't 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?

With 0% schema description coverage, the burden falls on the description, and it delivers: it explains the purpose of filters.ownership and filters.companyDomain, and previews the sortable/returned fields (queryCount, title, companyName). It doesn't mention cursor/limit/sorting, but those are structurally self-evident from the schema, so the description wisely spends its budget on the less-obvious ranking and filtering semantics.

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

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

The description names a specific verb ('List') and resource ('ranked pages tracked for a project'), and enumerates the exact fields returned (URL, title, company, query count, ownership). It immediately differentiates this from the many sibling list_* tools by the unique 'ranked pages' resource and the project scoping, so an agent can select it 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 states its filtering capabilities ('Filter by ownership or company domain') and defines its scope as project-tracked ranked pages, which cleanly distinguishes it from sibling list_* tools operating on other resources (keywords, competitors, opportunities). It doesn't explicitly name alternatives or exclusions, but the resource identity is clear enough that an agent wouldn't confuse it with, say, list_keywords.

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 covers safety, and the description adds meaningful behavior: pagination, sortability, the canonical name fallback chain (operator-set, site brand, niche name), and the precise meaning of lastActivityAt. This goes well beyond the annotation without contradicting it.

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 adds value: purpose, pagination/sorting, canonical name semantics, and recency meaning. It is front-loaded with the core action and avoids fluff, though the field semantics could be seen as slightly verbose relative to a simple list tool.

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

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

For a paginated read-only list with no output schema, the description provides key semantic anchors: name is the canonical identifier, niche.name is distinct metadata, and lastActivityAt drives disambiguation. It omits the default sort order and full response shape, but the essential decision-making context 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?

With 0% schema description coverage, the description must compensate. It explains the sorting values (createdAt, niche, industry) and mentions pagination, but it doesn't explain how cursor works or what limit's default/maximum implies. The sorting semantics are covered; the other two parameters are only implied.

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

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

The description starts with 'List all projects for the authenticated operator', giving a specific verb, resource, and scope. It also states pagination and sortable fields, making the tool's behavior clear and distinguishing it from singular get_project or create_project 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?

The description provides a concrete usage heuristic: when the operator refers to 'my project' without naming one, use the project with the highest lastActivityAt. It doesn't explicitly name alternatives or exclusions, but this rule gives actionable context for selecting the right project from the list.

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 in annotations, the safety profile is covered. The description adds a valuable behavioral fact: the tool returns null when the project has no radar snapshot, which is essential for handling the response. It also notes the per-topic suggestion counts, enriching the agent's understanding of the result 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?

Two sentences, no filler. The core action and resource are front-loaded, the return contents and null edge case are in the first sentence, and the alternative usage occupies the second. 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 single-parameter read operation, the description gives a thorough picture of the return value (topic fields, index, suggestion counts) and the null case, while directing to the next step via expand_radar_topic. With no output schema, this is largely sufficient; only minor details like ordering or pagination are absent, which are low-impact for a snapshot listing.

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

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

The schema has 0% description coverage for projectId, and the description only mentions 'for a project' in passing. It does not explicitly confirm that projectId is the unique identifier for the target project or explain any value format. With zero schema coverage, the description should take on the burden of parameter explanation, and it falls short.

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 ('List') and a concrete resource ('the latest emergent-topic radar snapshot for a project'), then enumerates the exact contents (label, summary, momentum, novelty, drivers, evidence, per-topic index, suggestion counts). It explicitly contrasts itself with expand_radar_topic, so there is no ambiguity about what this tool does or how it differs from its closest sibling.

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 directs the agent to use expand_radar_topic when the goal is to turn a topic into article angles, giving a clear alternative and the condition that triggers it. It also implies this tool is the listing step. It does not enumerate all exclusions, but the named sibling provides strong routing 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?

Annotations provide only readOnlyHint=false and destructiveHint=true, but the description goes far beyond: it lists all side effects, discloses that the IndexNow ping fires immediately, and explains the irreversible consequence of pinging a dead URL ('nothing re-pings later'). This gives the agent a real behavioral model of a mutation with lasting external 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?

The description is long, but every sentence earns its place: purpose, side effects, timing precondition, alternative path, sibling comparison, edge case, and parameter semantics each carry distinct information with zero filler. The core purpose is front-loaded in the opening sentence, and the caveats flow in logical order.

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

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

For a complex, destructive mutation with side effects and an irreversible external ping, the description covers essentially everything the agent needs: what happens, when to call, when not to, and the alternative. The only gap is return-value information — there is no output schema, and the description never states what the call returns — which is minor 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?

With 0% schema description coverage, the description compensates richly for publishedAt (ISO datetime, must not be in the future, when to provide it, why) and implicitly for publishedUrl (the URL that the article 'went live at'; without it the article is invisible to outcome tracking). The id parameter is only implied as 'the suggestion' rather than explicitly tied to the id field, which is a minor gap for a required 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 first sentence states a specific verb and resource: 'Record that an article went live at a URL.' It lists concrete side effects (flips suggestion to published, writes ledger row, stamps Passport, pings IndexNow) and explicitly differentiates itself from update_article_status, so an agent can unambiguously tell which sibling to invoke.

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 precondition ('Call it only once the URL actually resolves'), names the alternative for CMS-scheduled articles (update_article_status with scheduledFor, staying in ready_to_publish), and states exactly why this tool is preferred for the published transition (a status flip alone records no URL and breaks Search Console tracking). No usage decision is left 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 description explicitly states side effects: it appends a row (additive, non-destructive), never affects publish status or Search Console attribution, and scheduledFor is for display only. This aligns with the annotations (readOnlyHint false, destructiveHint false) and adds useful context about non-impact.

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 not wasteful; three sentences cover purpose, usage nuances, and parameter semantics without redundancy. Key constraints are front-loaded, making it easy to digest.

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 complexity of 5 parameters and 2 enums, the description covers all meaningful aspects: what it does, when to use, side effects, and parameter meanings. It also clarifies relationships with sibling tools, so an agent has full context. No output schema exists, so no return-value explanation is required.

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

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

With 0% schema description coverage, the description compensates fully. It explains each parameter: suggestionId (the source suggestion), kind (via examples like carousel PDF, social post), url (the asset link), channel (with allowed values), and scheduledFor (future post date for display only). No parameter is left undefined.

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

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

The description clearly states the tool's purpose: registering a derived asset (social post, video, etc.) from an article suggestion and appending a distribution-ledger row. It distinguishes itself from related tools like mark_article_published (which handles article publication status) and get_article_suggestion (which returns the derivatives).

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

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

The description provides explicit when-to-use guidance: use for any derived asset from an article suggestion, and clarifies that repeat posts can be registered again with a new URL. It also contrasts with mark_article_published, saying to use that for the article itself, leaving no ambiguity.

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 indicate destructiveHint=true, so the description correctly implies a mutating operation. It adds useful behavioral context: the tool is rate-limited per site and returns an error with wait time when the cooldown is active, which is not in annotations. It could disclose what 'remap' means in terms of side effects (e.g., does it replace existing owned pages or append?), but the rate-limit behavior is a significant addition beyond 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 wasted words. The core action is front-loaded ('Re-crawl the project website and refresh its owned pages'), followed by usage guidance and a key behavioral caveat (rate-limiting). Perfectly sized for the tool's simplicity.

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

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

This is a simple single-parameter tool with no output schema. The description covers the purpose, when to use, and a critical behavioral detail (rate-limit). It does not mention what the success response looks like, but with no output schema, that's less critical. For a mutation tool, it could state what the outcome is (e.g., 'owned pages are updated'), but the rate-limit note compensates. Overall, it's nearly complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, meaning the schema provides no description for projectId. The description does not explain the parameter semantics beyond the obvious 'projectId' identifier. However, the parameter is a UUID with a clear format, and the tool's purpose implies it refers to the project whose asset should be remapped. Since there is only one parameter and its meaning is inferable from context, a score of 3 is appropriate; the description could add more (e.g., 'the ID of the project whose website asset to re-crawl') but 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 clearly states the tool's function: re-crawling the project website and refreshing owned pages. It explicitly names the resource (project website) and the action (re-crawl, refresh), and differentiates itself from siblings like resync_asset_profile and update_asset_profile, though it doesn't name them directly. However, the use case with get_project_asset and mappingStatus is highly specific and distinguishes it from other mutation 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 provides explicit when-to-use guidance: when get_project_asset shows mappingStatus 'error' or owned pages look stale. It also mentions rate-limiting and the error response that names wait time, which helps the agent decide whether to call it or wait. While it doesn't explicitly say 'do not use when X', the conditions imply the alternative (get_project_asset) and the cooldown error guides the agent away from repeated calls.

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 the description adds substantial behavioral detail: it overwrites profile facts, leaves unsupported fields unchanged and never nulls them, stamps profileSyncedAt, leaves the niche untouched, and is rate-limited with an error naming the wait time. This is exactly the kind of context that helps an agent predict 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?

The description is four purposeful sentences, front-loaded with the core behavior and followed by trigger, side effects, and rate-limit behavior. Every sentence adds unique information and there is no repetition of the tool name or 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 mutating tool with no output schema, the description covers the trigger, what gets overwritten, the preservation rule, untouched niche, timestamp stamping, and rate-limit error behavior. An agent has enough context to decide when to call it and what to expect on both success and cooldown paths.

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

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

Schema description coverage is 0%, so the description needed to explain projectId, but it never mentions the parameter. The schema's property name and UUID format are self-evident, but the description adds no semantic guidance about how to obtain or use the projectId. With only one parameter, the gap is not fatal, but it is still a real compensation miss.

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 ('re-read the project website and re-infer the asset profile'), the exact resource affected, and the fields involved. It also distinguishes this from related tools by stating that it derives facts from current site content and does not touch the niche.

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 precise trigger: 'Use before rendering a report when get_pitch_report_payload flags assetProfile.syncedBeforeRun.' This is strong when-to-use guidance with a rationale. It does not explicitly name alternatives like update_asset_profile or state when-not-to-use, so it falls just short of fully explicit sibling differentiation.

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 behavioral expectations: feedback is a note to the team, not a ticket, so no promise of fixes; there is no reply, so the agent shouldn't wait for one. This goes beyond the annotations, which only indicate non-read-only and non-destructive. It doesn't mention any side effects like logging or rate limiting, but for a feedback tool this is sufficient.

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

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

The description is well-structured with clear clauses, but it has some redundancy (e.g., repeating 'Feedback is a note to the team, never a ticket' and 'do not promise the operator it will be fixed'). It is not overly long and the key information is front-loaded, but it could be trimmed slightly without losing clarity.

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 purpose, usage triggers, exclusions, and expected outcomes (no reply). It is missing parameter-level semantics and doesn't mention what happens after submission (e.g., where the note goes), but given the tool's simplicity and the annotations, it provides enough context for correct invocation. The lack of output schema is acceptable since the description notes there is no reply.

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

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

The schema has five parameters (kind, detail, summary, projectId, toolContext) but the description only implicitly references 'kind' by listing the feedback types. It provides no explanation of what each parameter means, their requiredness, or how to fill them, leaving the agent to infer from names alone. This is a significant gap given the schema coverage is 0%.

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

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

The description clearly states the tool's purpose: to file a note to the VarynForge team, enumerating the types of feedback (bug, missing capability, friction, idea). It also distinguishes itself from other tools by specifying what it is not (a ticket system) and explicitly excluding entitlement walls, making it 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 provides explicit when-to-use guidance: call when encountering something VarynForge cannot do, confusing results, or operator frustration/wishes. It also gives negative guidance, telling the agent not to file payment/rate/feature errors, which are working as designed. This is exceptionally 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 annotations' destructiveHint, the description discloses the 1.25x boost, top-10 cluster condition, post-normalization effect on relative rankings, the cross-check via get_opportunity_detail.rawOpportunityScore, and what ignored does to surfaces and the editorial-score pipeline. This is exceptional behavioral disclosure.

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

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

Three sentences with no filler: the first states the operation, the second covers the nontrivial scoring side effect and recovery path, and the third defines the ignored state. Valuable information is front-loaded and every sentence earns its place.

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

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

For a mutating tool with a destructiveHint, the description covers the side effects and even tells the agent how to verify raw scores. It is slightly incomplete only in that it does not describe the response or the neutral 'default' behavior, but nothing blocks 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 0%, so the description must compensate. It enriches 'importance' by explaining important and ignored, but it does not define 'default' or explicitly map companyId/projectId to the competitor and project. The parameter names and UUID formats carry the remaining 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 opens with a specific verb-resource pair, 'Mark a competitor important, default, or ignored,' and then details the meaningful consequences of each state. This clearly distinguishes the tool from read-only siblings like list_competitors and get_competitor_detail, and from add_competitor_by_domain.

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 described action ('mark a competitor...') makes the use case clear, and the scoring consequences indicate why an agent would choose this over read/list tools. It does not explicitly name alternatives or exclusion conditions, but the context is sufficient for a sibling-aware 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?

Annotations already indicate destructiveHint=true, and the description adds context about replacement behavior, persistence across research re-runs, and the effect on scoring/harvesting. It doesn't contradict annotations and gives meaningful extra behavioral detail beyond the structured 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?

The description is compact and well-structured: main purpose first, then examples, then behavior notes. Every sentence adds value, with no redundancy or filler.

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

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

For a simple two-parameter tool with destructive annotations, the description covers semantics, replacement behavior, and persistence. It doesn't mention return values or errors, but given no output schema and the simplicity, this is sufficient. The only gap is explicit permissions or reversibility, but the destructiveHint covers the risk.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'terms' parameter thoroughly (array of strings, replacement semantics, clearing with []) and gives examples. The 'projectId' parameter is self-evident from the name and type; no additional description needed.

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

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

The description clearly states the tool sets project-level exclusion terms, with specific verb and resource, and gives concrete examples ('wedding suite', 'free template', 'printing'). It distinguishes this from other setters by focusing on exclusion terms and their effect on scoring and harvesting.

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 usage context: it replaces the whole list, can be cleared with [], and survives research re-runs unlike per-cluster dismissal. This implies when to use it over alternatives, though it doesn't explicitly say 'use this when...' or list all 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?

Annotations already mark this as destructive (destructiveHint: true) and not read-only (readOnlyHint: false). The description adds nuance by explaining that dismissal lasts until the next research run and that removing a cluster affects the normalization of remaining clusters, which are valuable behavioral details 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?

The description is concise, containing three sentences that each add value: state purpose, describe effects, and contrast with an alternative. No redundant information; structure is logical with a clear flow.

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 need not discuss return values. It covers the core functionality, side effects, and provides usage context. Minor omissions like error handling or prerequisites are not critical given the simplicity of the tool, but a brief note on required permissions or potential failure modes could enhance 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?

Schema coverage is 0% with no parameter descriptions. The description explains the meaning of the 'status' parameter (dismissed vs. default) and implies the role of clusterId and projectId, but it does not explicitly define what these IDs represent or how they relate to each other. This leaves some ambiguity for the agent.

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

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

The description clearly states the tool's function: dismiss or restore an opportunity cluster by setting status to 'dismissed' or 'default'. It also explains the specific effects on list_opportunities and create_content_plan_from_opportunities, distinguishing it from 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?

Explicitly states when to use the tool (to dismiss or restore) and provides an alternative for a different use case (set_excluded_terms for durable 'not my product' signals). It also clarifies the temporary nature of dismissal, giving context for the tool's lifecycle.

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=false and destructiveHint=true, and the description adds value beyond them by explaining what the destructive consequence actually is: it resizes the pitch report's 90-day content sequence. It also discloses read-back via get_project.postsPerWeek. 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?

Two sentences, each earning its place: the first front-loads the core action and range, the second states the downstream effect and verification path. No filler, no 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 simple 2-parameter setter with no output schema, the description covers everything an agent needs: what is set, the valid range, the behavioral consequence on the pitch report, and how to verify the value afterward. Nothing essential 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 0%, so the description must compensate. It explains postsPerWeek's semantics ('how many articles per week the operator actually publishes' plus the 1-14 range) and its downstream meaning (sizing the sequence). projectId is left unexplained, but it is a self-evident UUID identifier implied by the get_project reference; the main meaningful parameter is well covered.

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

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

The description states a specific verb ('Set'), a clear resource (posting cadence / posts per week), and the value range (1-14). It distinguishes itself from sibling setters like set_competitor_importance and set_excluded_terms, which target different resources, so an agent can select it 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 provides clear context on when this matters — it sizes the pitch report's 90-day content sequence — and names the verification path via get_project.postsPerWeek. However, it does not explicitly state when not to use it or name alternatives (e.g., where cadence is initially configured), so it falls just short of explicit 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?

The description discloses material behaviors beyond the annotations: it consumes one credit, runs asynchronously (requiring polling), and returns a different payload on the free plan. These are non-obvious consequences that affect invocation and expectation management. The description does not contradict the readOnlyHint=false/destructiveHint=true 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 tight sentences with no filler: purpose and effects first, then cost and response contract. Every sentence adds necessary information, and the most decision-relevant detail (what the tool does) 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 one-parameter asynchronous mutation with no output schema, the description covers the return value ({ runId }), the progress-tracking mechanism, and the free-plan alternate response. Error cases and insufficient-credit behavior are not described, but those are not required for selecting or invoking 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 has zero description coverage, so the description carries the burden of explaining the lone 'id' parameter. 'Start a research run for a project' strongly implies that id is the project identifier. However, it is not stated explicitly as 'id is the project ID,' so the mapping is slightly implicit.

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 ('Start a research run'), names the resource (a project), and describes what the run does: discovers keywords, evaluates competitors, and writes opportunity clusters. This clearly differentiates it from the many read/status sibling tools by framing it as an initiating action with concrete effects.

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 the agent to poll get_research_status for progress after receiving a runId, pointing to the correct follow-up sibling. It also signals that this tool starts work rather than checking status or listing outputs. It does not enumerate when-not alternatives, but the async routing is clear and sufficient for correct use.

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 declare destructiveHint=true and readOnlyHint=false, so the agent already knows this is a mutation. The description adds valuable nuance: setting status to published here records no URL, the scheduledFor holds a 'stalled at ready_to_publish' flag until the schedule lapses, and publish auto-detect behavior is described. This goes beyond the annotations and helps avoid side-effect pitfalls.

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 not wasteful. The first sentence states the core purpose, the second sentence addresses the key alternative, and the third explains scheduling behavior. It is longer than typical but each clause serves a distinct instructional purpose. The structure is logical and front-loaded with the most important 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?

Given a mutation tool with no output schema and 4 parameters, the description covers the main operational concerns: the status transitions, the sibling tool divergence, and the scheduling edge case. It could mention return values or success indicators, but that is not essential for an agent to invoke it correctly. Overall it is sufficiently complete for the tool's complexity.

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

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

With 0% schema description coverage, the description must compensate. It explains the status enum as a progression of pipeline stages and clarifies the semantics of scheduledFor (planned date, flag behavior). It does not explain lastActor, but that parameter's purpose is somewhat inferable. The key parameters receive meaningful elaboration.

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: 'Move an article through the production pipeline', and enumerates the status values. It clearly distinguishes itself from the sibling mark_article_published by stating that the published transition should use that tool instead, removing any ambiguity about scope.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'For the published transition use mark_article_published instead' and 'do NOT call mark_article_published before the URL is live'. It also explains the scheduledFor usage for future scheduling, giving the agent clear decision criteria.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds substantial behavioral detail beyond that: 'Only the fields you pass are written; arrays replace the whole list. No re-crawl happens. Clears the profileStaleAt flag.' These are important side effects and update semantics that are not in the schema or annotations, giving the agent full knowledge of the tool's impact.

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 sentences with no filler. It opens with the action and fields, then gives usage condition, then update behavior details, and ends with the flag-clearing side effect. Every sentence earns its place, and the structure is front-loaded with the essential purpose.

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 write tool with 6 parameters and no output schema, the description covers all necessary operational aspects: what it does, when to use it, how updates behave (partial, array replacement), that it doesn't re-crawl, and that it clears an existing flag. There is nothing an agent needs to call it correctly that 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 0%, so the description must compensate. It explains the semantics of the parameters: fields are optional (only passed fields are written), and arrays replace the entire list, which is critical for correct usage. It names the fields but doesn't elaborate on each field's meaning, yet the names are self-explanatory. Slight deduction because it doesn't explicitly mention that projectId is required, though that is in the schema. Overall it adds meaning beyond the raw schema.

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

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

The description states a specific action ('Correct the inferred profile...') and enumerates the exact fields affected (description, primary offer, benefits, key differentiators, use cases). It distinguishes the tool from siblings like resync_asset_profile by explicitly noting that no re-crawl happens, so an agent can tell what this tool does versus alternatives without 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?

Explicitly specifies the condition for use: 'Use when get_project_asset shows claims that contradict what the operator actually sells (profileStaleAt set, or the operator says so).' This gives a clear trigger, and the mention of 'No re-crawl happens' implicitly differentiates from resync_asset_profile. The description tells the agent exactly when to invoke 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 already declare readOnlyHint=false and destructiveHint=true, so the mutation/destruction profile is covered. The description adds one genuinely useful behavioral trait: 'omitted fields keep their current values', clarifying the partial-update semantics. However, it does not disclose what the destructive aspect damages or any consequences of an update.

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 lean sentences, front-loaded with the action and target, followed by usage timing and a key behavioral clause. Every sentence earns its place; no filler or repetition of schema type 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 an 8-parameter mutation with no output schema, the description covers purpose, timing, and merge semantics — a solid baseline. However, it does not describe the return/response value at all, which matters since no output schema exists, nor does it explain error conditions or what destructive side effects the update might trigger. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It lists most parameters semantically (industry, country, core problem, related terms), which goes beyond the bare schema properties, but it adds no format, constraints, or deeper meaning beyond what the schema's types and names already imply. The partial-update rule is the most valuable semantic addition.

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) and resource (niche profile) and enumerates the updatable fields (name, industry, language, country, target customer, core problem, related terms). This clearly differentiates it from sibling tools like update_asset_profile or update_article_status by naming the target resource.

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 when-to-use context: 'Use after the operator refines their market definition.' It does not name alternative tools or explicit when-not-to-use conditions, but the trigger for invoking it is well specified.

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