Analook — Competitor Intelligence

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

With no annotations provided, the description fully discloses key behavioral aspects: it is an asynchronous job submission, requires authentication, deducts 1 credit, takes 2-5 minutes, and returns a job_id immediately. It also documents both success and error return formats.

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 sections: intro, workflow, timing/auth, args, returns. Every sentence provides necessary information without fluff, and the most important action 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 an async job submission tool with no output schema, the description is complete: it explains the input, the immediate response, the polling mechanism, the retrieval step, and error cases. It also mentions the breadth of data sources, setting expectations for report content.

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 value for url (with examples), product_name (defaults to domain), and lang ('en'/'zh'). However, the required 'context' parameter and optional 'conversation_id' are not mentioned, leaving a gap. Since schema description coverage is low (40%), the description only partially compensates.

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 submits a competitor analysis job and specifies what it does (analyzes website across 15+ data sources, returns a job_id). This distinguishes it from sibling reporting tools like get_report_status 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?

It explicitly explains the post-submission workflow: use get_report_status(job_id) to poll and get_report(job_id) to retrieve results. It also notes typical duration (2-5 minutes) and authentication/credit requirements. However, it does not explicitly contrast with run_growth_audit or other submission 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?

With no annotations, the description carries full responsibility. It discloses that no authentication or credits are required and that it returns recently published public reports, covering key behavioral traits. It omits minor details like pagination or rate limits, but the essentials are present.

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

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

The description is concise and front-loaded, immediately stating the tool's purpose and return contents. The Args section adds category examples without unnecessary verbosity, 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 simple browse/list tool, the description covers return fields, authentication requirements, credit usage, and optional filtering. No output schema exists, but the return format is clearly stated. It does not mention result count or ordering, which are minor gaps for this 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?

Schema coverage is 67% (context and conversation_id are described), and the description adds value for the category parameter with concrete examples like 'AI / Agents' and 'Dev Tools'. However, it does not compensate for the context parameter's analytics purpose beyond the schema, so it provides moderate added semantic value.

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

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

The description clearly states the tool browses Analook's public competitor-intelligence report gallery and returns specific fields (product name, domain, category, link). It distinguishes itself from siblings like analyze_competitor by emphasizing public, no-credit access, making the purpose 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 advises using it to discover existing analyses before spending a credit on a fresh one, which is explicit when-to-use guidance. It implicitly references an alternative (fresh analysis costing a credit) but does not name sibling tools like analyze_competitor, so it lacks fully explicit 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose important runtime behavior: 'while running, only {status, progress} is returned.' It also specifies the return shape. But it omits error handling, required permissions, or what happens if the job fails or is not found, leaving significant 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?

The description is compact and structured with Args/Returns sections. Every sentence contributes either the tool's main behavior, the parameter key detail, or the async return behavior. No redundant or vague text.

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

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

With no output schema, the description supplies a clear return structure and explains the progress state, which is essential for an asynchronous job fetch. It also links the job_id source. Missing details include error statuses and how to interpret 'completed' vs 'failed', but for a fetch operation this is largely sufficient to use 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 67%, and the description compensates for the undocumented `job_id` parameter by explaining its origin and format ('ID from run_growth_audit() (starts with 'ga-')'). This adds meaning beyond the schema, which lists `job_id` with no description. The other parameters have detailed descriptions in the schema, so the incremental value from the description is moderate.

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: 'Fetch a Growth Audit's three reports... as Markdown.' It names the exact resource (Growth Audit) and the output format (Markdown), and the `job_id` reference to `run_growth_audit()` distinguishes it from sibling tools like `get_report` or `get_report_markdown`.

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 context by specifying that `job_id` comes from `run_growth_audit()`, and it mentions the progressive return behavior while running. However, it does not explicitly contrast this tool with alternatives like `get_report_status` or state when to use this versus `get_report_markdown`. Usage guidance is present but implicit.

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 the return type (full report dict), error semantics ({error} if not found/not ready), and prerequisites (completed status). This is solid behavioral transparency for a read-only fetch operation, though it doesn't mention side effects or rate limits—acceptable given the nature of the tool.

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

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

The description is well-structured with Args and Returns sections. The opening sentence is direct. The long list of report contents is informative and helps set expectations, though it could be trimmed without losing core value. Overall, it is 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?

In the absence of an output schema, the description explains the return value as a nested dict and lists its major components. It also covers error behavior. This is sufficient for an agent to understand the tool's outputs and prerequisites. It doesn't describe exact nesting, but that is not necessary for successful 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 coverage is 67% because context and conversation_id have descriptions. The tool description adds crucial semantics for job_id: 'ID from analyze_competitor(); status must be completed', which the schema lacks. This goes beyond the structured schema and compensates for the missing description.

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

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

The description states a specific verb and resource: 'Fetch the full competitor analysis report as structured JSON'. It clearly identifies the tool's output format and scope, distinguishing it from siblings like get_report_status (status) and get_report_markdown (presumably Markdown 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 gives clear usage context: job_id comes from analyze_competitor() and the status must be 'completed'. This implies a workflow and precondition. However, it does not explicitly mention alternative tools or when not to use this tool, so it stops 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?

With no annotations, the description carries the burden of disclosing behavior. It specifies the return format ({markdown: str} or {error: str}) and the precondition of job status being 'completed', which is useful. However, it does not elaborate on what happens if the status is not completed, potential error details, or any authentication/rate-limit considerations, leaving some behavioral ambiguity.

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 primary purpose, follows with usage suitability, and then presents the Args and Returns clearly. Every sentence provides essential information without unnecessary elaboration, making it efficient and 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 tool with no output schema and no annotations, the description covers the essential aspects: what the tool does, when to use it, the required input, and the return type. It also mentions the status prerequisite. However, it lacks explicit details about error scenarios and how this tool relates to the sibling get_report, though the mention of 'structured JSON' hints at that. Given the simplicity of the tool, the description is nearly complete.

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

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

The description adds meaning beyond the schema by documenting the job_id parameter: 'ID from analyze_competitor(); status must be completed.' This compensates for the schema's lack of a description for job_id. The context and conversation_id parameters are already thoroughly described in the schema, so the description does not need to repeat them. Overall, the description fills the gap in parameter understanding.

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 with a specific verb and resource: 'Fetch the competitor analysis report as human-readable Markdown.' It distinguishes itself from the sibling get_report by emphasizing the Markdown format, and the additional note about piping into agents that prefer text further differentiates its use case.

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 guidance on when to use the tool: 'Suitable for piping into agents that prefer text over structured JSON, or for direct display to end users.' It also includes a prerequisite that job_id must come from analyze_competitor() and status must be 'completed'. While it does not explicitly name alternative tools, the suitability note implies when it should be chosen over structured JSON retrieval.

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 behavioral disclosure burden. It provides the return format (status, progress, report_url) but doesn't mention error behavior or whether polling is idempotent. This is adequate but not comprehensive.

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 purpose statement, an args section, and a return format. Every sentence adds value with no filler.

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

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

For a simple status polling tool, the description provides the return schema and job origin. It doesn't cover error handling or conversation_id, but those are partially handled by the schema, making it sufficient overall.

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 lacks description for job_id, and the description fills that gap by defining it as 'ID returned from analyze_competitor()'. The other parameters (context, conversation_id) already have schema descriptions, so the description doesn't need to 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 clearly states 'Poll an analysis job's status' with a specific verb and resource. It also identifies the source of the job_id as analyze_competitor(), which distinguishes it from sibling report retrieval 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 indicates job_id comes from analyze_competitor(), giving clear context for when to call. It doesn't explicitly mention alternatives like get_report, but the status return shape makes the intended use obvious.

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?

Without annotations, the description carries the transparency burden. It discloses authentication requirements, the limit of 50 items, the lightweight field set, and the recommended follow-up action. It does not mention sorting order or error behavior, but the essential behavioral traits for a list operation are 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 concise and front-loaded with the purpose. It includes useful behavioral notes in a compact form, though the return structure is described twice (once in prose and once in a Returns block), creating slight redundancy that could be trimmed.

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 listing tool with no output schema, the description adequately covers the return format, authentication, limit, and a pointer to the next step. It does not specify sorting or the meaning of 'recent,' but the overall picture is sufficient for an agent to invoke the tool and interpret results.

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% for both parameters (context and conversation_id), so the tool description adds no additional parameter-level meaning. The baseline of 3 applies because the schema already provides detailed descriptions; the tool description does not enhance or clarify them further.

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 ('List'), the resource ('your recent competitor analysis reports'), and a key constraint (up to 50). It distinguishes itself from sibling tools by noting that full reports require get_report(job_id), making the purpose unambiguous and well-differentiated.

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

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

The description provides clear context for use: it is the listing entry point for recent reports and points to get_report for full details. It lacks an explicit exclusion for browse_public_reports, but the focus on 'your' reports makes the appropriate use case apparent.

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 states the operation takes ~4-6 minutes, requires authentication, deducts 10 credits, and is async (poll with get_growth_audit). These are precisely the non-obvious behaviors an agent needs to know.

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: a one-line summary, a comparison sentence, operational details (time, auth, credits, polling), and a compact Args list. Every sentence serves a purpose, and no content is redundant or filler. It is appropriately detailed for a complex async 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?

The description covers the high-level business logic well, but it omits two parameters (context and conversation_id) from its Args section. The required context parameter is entirely absent from the description, which could mislead an agent into thinking only url is required. The schema fills this gap, but the description itself is incomplete for such 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 40% (low), so the description must compensate. It adds meaningful semantics for url, product_name, and lang (e.g., product_name defaults to domain, lang supports 'en'/'zh'). However, it omits the required context and conversation_id parameters, which the schema already describes. The description adds value for most business params but is incomplete in its Args list.

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: 'Run a full Growth Audit — three linked strategic reports for a product.' It explicitly lists the outputs (Executive Summary + Diagnosis Report + 30-day Action Plan) and distinguishes it from the sibling analyze_competitor, so the agent knows exactly what this tool does and how it differs.

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 versus alternatives: 'Unlike analyze_competitor... Best for how do I grow THIS product rather than what is this competitor doing.' It also instructs the agent to poll with get_growth_audit(job_id) after running, which is a key usage step.

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