Analook — Competitor Intelligence

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

With no annotations provided, the description carries full behavioral burden. It discloses that the tool is asynchronous, takes 2-5 minutes, requires authentication (deducts 1 credit), and provides both success and error return shapes. This goes beyond simple mutation warnings and gives cost and flow 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 well-organized into an introductory sentence, Args block, and Returns block. Every sentence adds distinct value (scope, flow, timing, cost), with 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?

The async job submission pattern, cost, expected duration, and follow-up steps are all explained. The return format is specified despite no output schema, and the data sources are enumerated, making the tool's behavior fully understandable.

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 Args section adds meaningful semantics for url (accepts domain or full URL with examples), product_name (defaults to domain), and lang (en/zh defaults). It omits context and conversation_id, but both already have detailed descriptions in the schema, so the description's coverage of domain-specific parameters is sufficient.

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 'Submit a competitor analysis job' and details the analysis scope (15+ data sources), making the tool's function specific and distinct from report retrieval tools. It clearly indicates this is for competitor websites and returns a job_id, setting it apart from sibling tools like get_report_status and run_growth_audit.

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 to use get_report_status(job_id) for polling and get_report(job_id) after completion, and mentions typical analysis duration for timing expectations. However, it doesn't explicitly contrast with run_growth_audit or other alternatives, so the when-not guidance is missing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that no auth/credits are needed and lists return fields, but does not mention pagination, result limits, sorting, or any potential rate constraints. It adds some useful context but lacks depth for a complete safety/behavior profile.

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

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

The description is compact and front-loaded: first sentence states purpose, second describes output and access, third gives usage rationale, and the Args section provides a helpful parameter example. Every sentence earns its place with 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?

For a simple browse tool, the description covers the main function, return fields, auth/credit requirements, and a category filter example. It lacks details on result limits, pagination, or how the link is presented, but these are minor gaps given the tool's simplicity. No output schema exists, so some return detail in the description is valued.

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 67%, and the tool description adds value primarily for the 'category' parameter with examples ('AI / Agents', 'Dev Tools', etc.). The 'context' and 'conversation_id' parameters are already well-described in the schema, so the description does not need to compensate heavily. Overall, adequate but not exceptional.

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: 'Browse Analook's public competitor-intelligence report gallery' and specifies what it returns ('recently published public reports (product name, domain, category, and a link)'). This distinguishes it from siblings like get_report (single report retrieval) and analyze_competitor (creating new analyses), using a specific verb and 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 usage context: 'a fast way to discover existing analyses before spending a credit on a fresh one' and notes 'No authentication or credits required.' This implies when to use it (before generating new analyses), though it does not explicitly name alternatives or state when not to use it. Thus slightly short of a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that while the audit is running, only {status, progress} is returned, which is a key dynamic behavior. It also specifies the exact return structure with report keys, adding valuable context beyond the schema.

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

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

The description is concise and well-structured with Args and Returns sections. It uses only two sentences plus the structured details, with no wasted words. The main purpose is front-loaded in the first sentence.

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

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

The description explains the return shape, the Markdown format, the progressive return behavior, and the source of job_id. It does not mention error handling or invalid job_id conditions, but for a simple fetch tool with no output schema, this is fairly complete. Sibling tools like get_report_status are not referenced, but the job_id linkage covers the primary usage context.

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

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

The description provides critical semantics for job_id: it is the ID from run_growth_audit() and starts with 'ga-'. The schema only defines job_id as a type, so this fills a gap. The context and conversation_id parameters have schema descriptions, so overall parameter understanding is strong.

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

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

The description states a specific verb ('Fetch') and a specific resource ('a Growth Audit's three reports') in Markdown format. This clearly distinguishes the tool from siblings like get_report or get_report_markdown, which might fetch individual reports or other markdown documents.

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 that job_id comes from run_growth_audit(), clearly implying this tool should be used after launching a growth audit. It does not explicitly state when not to use it or name alternative tools, but the job_id dependency gives strong contextual guidance.

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

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

With no annotations provided, the description carries the burden. It discloses that the tool returns either a full nested dict or an error for missing/incomplete reports, and it explains the content scope (website snapshot, Wayback, SEO, etc.). It does not discuss auth, rate limits, or side effects, but for a read-only fetch these are less critical.

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 a lead sentence, an Args/Returns format, and a precise list of report contents. The list of data sources is somewhat long but serves as useful context for an agent selecting the right tool. It is front-loaded and does not waste words on filler.

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

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

Given the lack of output schema and annotations, this description is fairly complete: it specifies the return type, error behavior, and a prerequisite. It also enumerates the report's contents, which helps an agent judge whether the data matches the user's need. It could go deeper on the exact nesting or size, but for a typical retrieval tool it suffices.

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

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

The description adds meaning to job_id beyond the schema: it explains it is the ID from analyze_competitor() and that the report must have status 'completed'. The context and conversation_id parameters are adequately described in the schema, so overall parameter semantics are well covered despite the 67% schema coverage.

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

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

The description states a specific verb ('Fetch'), a clear resource ('full competitor analysis report'), and the output format ('structured JSON'). It distinguishes itself from sibling tools like get_report_markdown (presumably text/markdown) and get_report_status (status only), and 'full' differentiates from browse_public_reports.

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 clear prerequisite: job_id must come from analyze_competitor() and the status must be 'completed'. This implies the tool is for post-analysis retrieval and not for early polling. It also notes the error case ('not found / not ready'), but it does not explicitly name alternative tools for different report formats or status checks.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses the return type as {markdown: str} or {error: str} and the requirement that the job be completed. It does not mention error specifics, rate limits, or side effects, but for a read-only fetch this is acceptable; however, more detail could be provided.

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: a clear purpose statement, one use-case sentence, and structured Args/Returns sections. Every sentence earns its place with no redundancy.

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

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

The tool is simple; the description covers purpose, use cases, key parameter, and return format. It omits the required context parameter, but the schema documents it. It could more explicitly contrast with get_report, but the sibling list provides enough context. Overall, it is complete for the tool's 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 description adds meaningful context for job_id (source from analyze_competitor, status requirement) that the schema lacks (only 'Job Id'). It does not mention context or conversation_id, but those have detailed schema descriptions. With schema coverage at 67%, the baseline is 3, and the added job_id detail elevates it to 4.

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 fetches the competitor analysis report as human-readable Markdown, using a specific verb and resource. It distinguishes from siblings like get_report (likely structured JSON) by emphasizing the format and intended use cases.

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 it is suitable for piping into agents preferring text or for direct display, implying a contrast with structured JSON alternatives. It also provides a clear precondition: job_id must come from analyze_competitor and status must be 'completed'. It does not name alternatives explicitly but gives enough contextual guidance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It documents the return structure (status, progress, report_url) and the polling nature, which is helpful. However, it does not mention side effects, rate limits, or error handling, though the read-only nature is implied.

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

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

The description is extremely concise: two short sections for arguments and returns, with no wasted words. Every sentence contributes essential information, making it easy to scan and understand quickly.

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, the description covers the main usage pattern and return values. It does not mention the required 'context' parameter or the optional 'conversation_id', but the schema provides those details. Minor gaps in error behavior or pagination are acceptable for a polling 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 description adds important meaning to job_id by stating it is the 'ID returned from analyze_competitor()', which is not present in the schema. The context and conversation_id parameters are already described in the schema (coverage 67%), so the description complements it well for the otherwise unexplained job_id.

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

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

The description clearly states the tool's function: 'Poll an analysis job's status.' It uses a specific verb and resource, and the reference to job_id from analyze_competitor() distinguishes it from sibling tools like analyze_competitor and get_report.

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

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

The description implies when to use it—after calling analyze_competitor() and waiting for results—by explaining that job_id is the ID returned from that function. It does not explicitly mention alternatives or when not to use it, but the polling context is clear.

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

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

With no annotations, the description must self-disclose behavior. It states that authentication is required, that the response is a lightweight list containing specified fields, and that there is a 50-item cap. This covers many important traits. However, it does not mention, for example, whether the results are sorted or if there are any pagination/error behaviors, which would make it even more transparent.

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

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

The description is compact and information-dense. It opens with the core purpose, then provides necessary operational details in three sentences, and includes a clearly formatted return structure. Every sentence earns its place and there is no redundancy or filler.

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

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

Since there is no output schema, the description correctly includes the return shape using a JSON-like block. It also covers the key context: authentication, the 50-item limit, the lightweight nature, and the path to the full report via a sibling tool. For a simple list operation, this is a complete specification.

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

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

The description does not explain the 'context' and 'conversation_id' parameters. However, the input schema provides descriptions for both (100% coverage), so the baseline is 3. The schema descriptions are generic and about the calling convention rather than the tool's domain, but they still fulfill the need. The description itself adds no extra parameter 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 'List your recent competitor analysis reports', which specifies the action (list) and the resource (my reports). The 'my' clearly distinguishes this from the sibling browse_public_reports, and the 'lightweight list' note differentiates it from get_report. The specific scope (up to 50) further sharpens the purpose.

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 to use get_report(job_id) when a full report is needed, thereby indicating when this tool should NOT be used (for full report content). It also sets a usage expectation with the 'up to 50' limit. This provides clear guidance on selecting between list and detail tools.

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

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

With no annotations, the description carries the full burden, and it delivers: discloses the ~4-6 minute runtime, authentication requirement, 10-credit cost, asynchronous nature, and the polling mechanism via get_growth_audit. It stops short of detailing failure modes or edge cases, but the provided context is substantial for an unannotated tool.

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

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

The description is front-loaded with the core action, then moves efficiently through sibling comparison, usage guidance, async behavior, and parameters. Every sentence contributes meaningful information without redundancy or padding, making it appropriately sized for the tool's complexity.

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

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

For a multi-report, credits-based, asynchronous tool, the description is remarkably complete: it explains the output composition, the polling step, and the resource cost. However, it misses the required 'context' parameter and the 'conversation_id' echo requirement, which are part of the full calling contract, slightly reducing 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 description coverage is low (40%), so the description must compensate, but it covers only url, product_name, and lang, adding reasonable meaning (e.g., product_name defaults to domain, lang accepts 'en'/'zh'). Critically, it omits the required 'context' parameter and 'conversation_id', both of which carry important instructions in the schema. This gap prevents a higher score.

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

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

The description opens with a specific verb and resource: 'Run a full Growth Audit — three linked strategic reports for a product.' It clearly distinguishes itself from the sibling tool analyze_competitor by detailing the three-report output (Executive Summary, Diagnosis Report, 30-day Action Plan), 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?

Explicitly contrasts with analyze_competitor ('a single 15-signal intelligence snapshot') and states the best use case: 'how do I grow THIS product' versus 'what is this competitor doing'. It also tells the agent when to use get_growth_audit for polling, covering both when-to-use and alternative.

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