Analook — Competitor Intelligence

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

With no annotations provided, the description carries the full behavioral burden and does so exceptionally: it discloses the async nature, the 2-5 minute duration, the auth requirement, the 1-credit deduction, and the exact success/error return shapes. An agent can accurately predict side effects and failure modes.

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 purpose, workflow, Args, and Returns sections; every sentence earns its place and the key workflow is front-loaded. The length is justified by the complexity of an async job with polling and retry implications.

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 workflow and return types are well covered, which matters especially because there is no output schema. But the description fails to document context, llm_model, and conversation_id — including two required fields — leaving a meaningful gap for an agent assembling a valid call from the description alone.

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

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

The description adds real value for url (with examples), product_name (defaults to domain), and lang ('en'/'zh'). However, the Args list omits three schema parameters — including required context and llm_model — so it does not fully compensate for the 50% schema coverage and could mislead an agent about which arguments are mandatory.

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 — 'Submit a competitor analysis job' — and elaborates with 'Analyzes a competitor's website across 15+ data sources'. It also names the downstream retrieval siblings (get_report_status, get_report), so an agent can distinguish submission from retrieval even before inspecting schemas.

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

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

The description explicitly tells the agent to poll with get_report_status(job_id) and retrieve with get_report(job_id) when status='completed', which is strong workflow guidance. It does not contrast with run_growth_audit or state when not to use this tool, so it stops short of full when/when-not coverage.

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 behavioral burden and does disclose key traits: no authentication or credits requiredhend having a 'link' in the output. It does not mention pagination or rate limits, but for a public read-only browse tool the disclosed traits are relevant and otherwise complete enough.

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 front-load the purpose and returned data, then add the cost/auth benefit and an Args hint. There is no filler, though the Args block covers only one of the four parameters.

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 spells out the return fields (product name, domain, category, link) and the key access constraints even without an output schema. It is mostly complete for a simple browse tool, though it omits any pagination, ordering, or result-limit caveats.

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

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

The description adds real value for the category parameter by providing concrete filter examples like 'AI / Agents' and 'Marketing / SEO' beyond what the bare schema field offers. The remaining parameters are already well described in the schema, so the 75% schema coverage is compensated.

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

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

Description uses a specific verb ('browse') and names the exact resource: Analook's public competitor-intelligence report gallery. It also lists the returned fields, making it clearly distinguishable from sibling tools like list_my_reports or 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?

It frames the tool as 'a fast way to discover existing analyses before spending a credit on a fresh one,' giving clear context for when it should be preferred over a new paid analysis. It does not explicitly name the alternative sibling tool, so it stops short of a full when-not-to-use guideline.

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

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

With no annotations provided, the description carries the full behavioral burden and does well by disclosing the async behavior: while running only {status, progress} is returned, while completed calls return the three reports. It does not cover error behavior or polling details, but the key stateful trait is 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 tight and well-organized with Args and Returns sections. The core purpose is front-loaded, and the async return behavior is described in one clear sentence with no filler.

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

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

For an async retrieval tool with no output schema and no annotations, the description adequately covers the main invocation flow and return states. It falls short only by not describing status values/polling behavior and not acknowledging the analytics-only parameters, but it is largely complete for correct invocation.

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

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

The description adds meaningful context for job_id by giving its provenance and format ('starts with ga-'), which the schema lacks. However, it omits the required analytics parameters (context, llm_model) and conversation_id entirely, leaving their purpose and requiredness to the schema 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 opens with a specific verb and resource: 'Fetch a Growth Audit's three reports (Executive Summary, Diagnosis, Action Plan) as Markdown.' This clearly identifies the tool's function and differentiates it from status-only or run-focused siblings, even without naming them.

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 after run_growth_audit() by referencing its job_id, and it explains the running state. However, it never explicitly says when to prefer this tool over get_report_status or get_report_markdown, and it provides no when-not-to-use guidance.

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

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

With no annotations, the description must disclose behavior itself. It does mention that it returns an error if not found or not ready, and lists the report contents. It does not mention authentication, rate limits, or that the operation is read-only, nor does it explain the required analytics parameters (context, llm_model) in the description. This leaves gaps, though the error condition is covered.

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

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

The description is well-organized: a front-loaded purpose statement, a concise list of report contents, then Args and Returns sections. Every sentence adds value, and the structure makes it easy to scan. It is informative without being verbose.

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 report is complex with many data sections and there is no output schema, so the description partially compensates by listing the major sections. It also specifies error behavior. However, it does not mention the required context and llm_model parameters, which an agent must provide; these are only documented in the schema. Given the complexity, it is fairly complete but not exhaustive.

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 75% (job_id lacks a schema description), so baseline is 3. The description adds crucial meaning to job_id by specifying its origin and the 'completed' status requirement, which the schema does not. The other parameters have adequate schema descriptions, so the description compensates for the one gap.

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

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

The description clearly states the verb 'Fetch', the resource 'full competitor analysis report', and the format 'structured JSON'. It distinguishes from siblings like get_report_markdown and get_report_status by specifying the JSON format and full content, and the list of sections clarifies 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?

It gives clear context that the job_id comes from analyze_competitor() and must be 'completed' before the report is available, implying use after analysis. However, it does not explicitly mention alternatives like get_report_markdown or get_report_status, so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full disclosure burden. It clearly signals that this is a read operation ('Fetch'), documents the response contract ('{markdown: str} or {error: str}'), and adds an important precondition ('status must be completed'). It does not detail error conditions or safety nuances, but for a simple fetch tool this 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?

The description is compact and front-loaded: the purpose appears in the first sentence, utility guidance in the second, and Args/Returns are tersely formatted. Every sentence earns its place with no filler or repetition of schema content.

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

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

For a 4-parameter read tool with no output schema, the description provides the essential contract: return shape, error shape, and the completion precondition. The schema covers the analytics boilerplate parameters. Minor omissions like explicit alternative routing and more detailed error behavior keep it from being 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 coverage is 75%, so the baseline is 3. The description adds real semantics for the only undocumented parameter, job_id, by specifying its source ('ID from analyze_competitor()') and its required state ('status must be completed'). The remaining analytics parameters are already well-described in the schema, so no duplication is 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 opens with a specific verb-resource pair: 'Fetch the competitor analysis report as human-readable Markdown.' It also differentiates from the likely structured-JSON sibling by stating it is 'Suitable for piping into agents that prefer text over structured JSON,' so an agent can distinguish this from get_report without inspecting schemas.

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

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

The suitability line gives clear context for when this tool is preferred ('piping into agents that prefer text... or for direct display to end users'), and the Args note warns that job_id must come from analyze_competitor() with status 'completed.' However, it never explicitly names alternative sibling tools or states when NOT to use this tool, so the guidance is strong but not fully explicit.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the exact return shape including possible status values and optional fields. It does not cover failure semantics or polling frequency, but the core polling behavior is clearly specified.

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 with a one-sentence purpose, Args, and Returns blocks. Every line earns its place, and the most important information is front-loaded.

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

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

Given the simple tool shape, the schema covers the analytics-only parameters and conversation_id, while the description covers job_id and the return contract. Since there is no output schema, the Returns block is essential and is 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?

The schema gives job_id only a title with no description, so the description adds real value by explaining it is the ID returned from analyze_competitor(). The remaining parameters already have descriptive schema entries, so the description need not repeat them.

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

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

The description opens with a specific verb and resource: 'Poll an analysis job's status.' It is clearly distinct from sibling tools like analyze_competitor and get_report, and the job_id origin ties it to a concrete workflow.

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

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

The description implicitly establishes when to use it by noting the job_id comes from analyze_competitor(), making the polling workflow clear. It does not explicitly contrast it with get_report or get_report_markdown, but the polling intent is unambiguous.

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

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

With no annotations, the description carries the full burden and does a good job: it states that authentication is required, that results are limited to 50, that the output is a lightweight summary rather than full reports, and it names the exact fields returned. It does not mention ordering or pagination, but for a simple list operation this is reasonably 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 well-structured, front-loading the purpose and then giving the return shape and a pointer to the sibling tool. The 'Returns:' block slightly duplicates the parenthetical field list in the first paragraph, but overall the text is compact 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 low-complexity list tool with no output schema and no annotations, the description provides the essential information: authentication, result cap, return shape, and how to get full reports. Missing details like ordering or possible status values are minor and unlikely to prevent correct use.

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%, so the parameters are already fully documented in the input schema; the description adds no parameter-level meaning. The parameters appear to be analytics/metadata fields rather than listing filters, and the description does not discuss them, but the schema covers them adequately, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('List your recent competitor analysis reports'), with an explicit cap of 50 and a concise field list. It also distinguishes itself from get_report by noting that the full report must be fetched separately, so an agent can tell this tool apart from its 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 gives clear context: use this tool to get a lightweight overview of the user's own reports, and use get_report(job_id) to fetch full details. It does not explicitly enumerate when not to use it versus browse_public_reports or get_report_status, but the scoping to 'your recent reports' and the explicit pointer to get_report provide enough routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the runtime (~4-6 minutes), authentication requirement, credit deduction (10 credits), and the asynchronous polling pattern. This goes well beyond the minimum required 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?

The description is well-structured and front-loaded: purpose, differentiation, usage, behavioral notes, and args. Each sentence earns its place. The only deduction is the incomplete Args list, which omits three schema parameters and could mislead an agent relying solely on the description.

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 output deliverables (Executive Summary, Diagnosis Report, 30-day Action Plan), the async polling workflow, and the cost. However, it does not mention the required analytics parameters (context, llm_model) that the agent must supply, and with no output schema this is a notable gap in guiding a 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?

The description adds meaningful semantics for url, product_name, and lang, none of which have descriptions in the schema. However, it completely omits the required params context, llm_model, and conversation_id, which account for half the schema. With 50% schema coverage, the description only partially compensates for the missing parameter 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 runs a full Growth Audit with three linked strategic reports, explicitly differentiating from analyze_competitor by naming the output components and the use case ('how do I grow THIS product'). This makes the purpose unambiguous and distinguishes it from siblings.

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

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

The description explicitly tells when to use this tool versus analyze_competitor ('Best for... rather than...') and explains the async workflow with get_growth_audit for polling. It also states the expected duration and cost, leaving no ambiguity about the usage context.

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