LinkPulse

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

Describes data sources (WeCanTrack and LinkPulse) and empty return behavior. Lacks disclosure of potential performance, pagination, or authentication needs. No annotations provided, so description partially fulfills 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 efficient sentences with no wasted words. Front-loaded with purpose, followed by data source and edge case. Perfectly proportioned for the information conveyed.

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 single parameter, no output schema, and no annotations, the description covers key aspects: what it returns, when it returns empty, and data origin. Could optionally mention typical output fields like article URL or commission amount.

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

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

Only one parameter (days) with full schema description; description adds no extra meaning beyond what the schema already provides. Baseline score of 3 applies due to 100% schema coverage.

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

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

Clearly states the tool returns articles with both affiliate commissions and broken links, a cross-join of revenue and link data. Distinguishes from siblings like broken_links and revenue_summary by specifying the combined intent.

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 says to use when answering 'where am I losing money' and prioritizing fixes. Mentions empty return condition but does not explicitly exclude cases like needing raw broken link lists or pure revenue summaries, though context implies alternatives.

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

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

With no annotations, description discloses behavior: returns currently flagged broken links, includes 4xx and 3xx, groups by post, from LinkPulse scanner. No destructive indications. Transparent for a read-only tool.

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

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

Two sentences, each adding value: first defines content, second gives usage context. No fluff 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 no output schema, description gives return concept ('grouped by post') but lacks detail on exact structure. However, simplicity and mention of piping to suggest_replacement provide adequate 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?

Input schema has 0 parameters (100% coverage), so baseline is 4. Description adds no param info because none 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?

Description clearly states the tool returns all broken affiliate links flagged by LinkPulse scanner, including 4xx and 3xx status codes grouped by post. It distinguishes from siblings like suggest_replacement and top_articles by specifying 'broken affiliate links'.

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

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

Description explicitly mentions usefulness for 'audit-style questions' and for 'piping into suggest_replacement,' providing context for when to use. However, it does not explicitly state when not to use or compare to other 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?

No annotations are provided, so the description must disclose all behavioral traits. It describes the data returned and the data source (WeCanTrack via LinkPulse). It does not mention side effects, rate limits, or other constraints, but as a read-only query, the transparency is adequate.

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

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

Two concise sentences with no wasted words. Every part adds value: the output details, the data source, and the default window. Front-loaded with the key information.

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

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

Given the single parameter, no output schema, and simple behavior, the description fully explains what the tool returns and the source. No gaps remain for the complexity level.

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

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

Schema coverage is 100% for the single parameter 'days', which already provides constraints and description. The main description adds 'over a window (default 30 days)' but does not meaningfully augment the schema. Baseline of 3 applies.

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

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

The description clearly states the tool returns total affiliate commissions, transaction count, average commission, and delta over a window. The verb 'summary' and specific output metrics make the purpose unambiguous. It naturally distinguishes from sibling tools which deal with articles and links.

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 context (data source, default window) but does not explicitly state when to use this tool versus alternatives or exclude scenarios. The usage is clear enough from the purpose, earning a 4.

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 tool uses Claude with web search, which implies an LLM call and potential network requests. It also lists the returned fields. With no annotations provided, the description carries full burden, and it does a reasonable job, though it could mention rate limits or error behavior.

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

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

The description is three sentences, front-loaded with the core action. It is efficient but includes a forward-looking mention of apply_fix that, while contextually useful, is not strictly necessary for the current tool's use. Still, no wasted words.

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

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

The description covers the input (broken URL, article), the process (web search via Claude), and the output (candidate, reasoning, confidence, reachability). It does not address error scenarios or prerequisites like having identified a broken link, but overall it provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the schema documents each parameter. The description adds value by explaining that the article title provides context for the search, but it does not significantly extend understanding beyond what is in the schema. A baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: given a broken affiliate URL and its article context, it asks Claude with web search to find the closest alternative product. It returns specific outputs (candidate URL, reasoning, confidence, reachability check). This distinctly separates it from sibling tools which focus on listing/reporting rather than suggesting fixes.

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 specifies when to use the tool: when a broken affiliate URL is identified and an article context is available. It also mentions that the output is consumed by apply_fix, hinting at the workflow. However, it does not provide explicit exclusions or alternatives, which would improve 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 reveals the key behavioral detail that URL grouping strips tracking parameters (e.g., ?gclid=), which is beyond the basic function. No annotations exist to contradict.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers the essential operation, key behavioral nuance, and practical use cases completely.

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

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

Schema description coverage is 100% with parameter descriptions. The tool's description adds no additional parameter meaning beyond 'window size' and 'max articles', so 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 clearly states the verb 'generated the most commission' and resource 'articles on the current site', and distinguishes from sibling tools like at_risk_articles and revenue_summary by focusing on top earners.

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 use cases ('which posts make money', 'where to spend editorial time') but does not mention when to avoid using the tool or suggest alternatives.

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