eyepup

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

No annotations are provided, so the description must disclose behavior. It states the return is 'LLM-grounded' with evidence and ranked actions, but does not mention potential latency, cost, or limitations of the LLM response.

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 pack purpose, usage guidance, and return description efficiently. No waste.

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 adequately explains the return type. However, it could mention that the answer is AI-generated and may need verification, but overall sufficient 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?

Schema description coverage is 100%, so baseline is 3. The description adds example queries but no additional meaning beyond the schema's 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 clearly states the tool answers natural-language questions about site visitors. It provides example queries and distinguishes from siblings by focusing on free-text questions.

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 usage scenarios ('when the user asks...') and example queries, helping the agent decide when to use this tool. However, it does not explicitly mention when not to use it or name alternative sibling 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 must disclose behaviors. It reveals that the dossier agent reasons about visitors after the log row and grades friction recovery, which is a useful side effect. However, it omits other traits like whether the action is destructive, authentication needs, or idempotency, leaving 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 three sentences with a clear front-loaded purpose ('Log a change you just shipped.'). Every sentence adds value: purpose, side effect, and usage instruction. No redundant or extraneous 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?

Given a simple logging tool with 5 parameters and no output schema, the description covers the core purpose and when to use it. However, it lacks parameter-level explanations and comprehensive behavioral traits (e.g., side effects on data, required permissions). Adequate but not fully complete for an agent to use without guessing parameter formats.

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% (only 'paths' and 'title' have descriptions). The tool description adds zero explanation for parameters like 'kind', 'site', or 'description'. For example, 'kind' has an enum but no guidance on selection. Thus, the description fails to compensate for missing schema 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 clearly states the tool logs a change shipped, with the explicit verb 'log' and resource 'change'. It adds context about the dossier agent reasoning, distinguishing it from sibling tools like eyepup_ask or eyepup_visitor. However, it slightly lacks specificity on the kind of changes beyond UX edits.

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 instructs 'CALL THIS after every UX edit', providing clear when-to-use guidance. It does not mention when not to use or suggest alternatives, but the usage context is direct and 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 provided, the description carries the full burden. It implies a read-only operation ('Get') and mentions that rows include a 'recommended_action,' but does not disclose potential side effects, authorization requirements, or pagination behavior. Somewhat adequate but lacks depth.

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 concise sentences: purpose, usage instruction, and a key output detail. No filler or redundancy. Front-loaded with the core action.

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 list tool with well-documented parameters and no output schema, the description provides enough context: ranked list, recommended action, and usage timing. Minor missing details like ordering direction, but overall complete for its 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema for the two parameters (site and limit). It does not elaborate on valid values or formatting.

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 retrieves top friction patterns ranked by impact score, which matches the title. It distinguishes itself from siblings like eyepup_ask or eyepup_visitor by focusing on friction patterns and a ranked to-do queue.

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 advises to use before making UX edits, explaining why the highest-impact pattern is more valuable. This provides clear context for when to invoke this tool vs. 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?

No annotations are provided, so the description must convey behavioral traits. It only mentions fetching a profile but does not disclose side effects, permission requirements, rate limits, or whether the operation is read-only. The description is insufficient for a tool with no 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 consists of two concise sentences that front-load the primary purpose and immediately provide usage context. Every sentence serves a clear purpose with no extraneous 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?

Given the tool has one required parameter, no output schema, and no annotations, the description is largely sufficient. It explains the action, input, and usage context. However, it does not describe the output format beyond 'full LLM-written profile,' which is somewhat vague. Still, it is mostly 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?

Schema coverage is 100% for the single parameter, and the schema already describes 'distinct_id' as a UUID string. The description adds no new information about parameter meaning beyond 'by distinct_id.' Thus, it meets the baseline but does not enhance 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 action ('Fetch the full LLM-written profile'), the resource ('for a single visitor'), and the required parameter ('by distinct_id'). It also distinguishes itself from sibling tools by noting it is used after eyepup_visitors_hot or eyepup_todo to delve into a specific visitor, leaving no ambiguity about its 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 indicates when to use this tool: 'Use after eyepup_visitors_hot or eyepup_todo to dig into a specific visitor.' While it lacks explicit 'when not to use' statements, the context of being a follow-up tool is clear, providing strong 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 must disclose behavioral traits. It only says 'return the top high-intent visitors currently active' but does not explain what 'high-intent' means, how visitors are determined, data freshness, or any side effects. The description is too minimal for a tool with no 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 long, directly stating the function and usage context. Every word earns its place; there is no unnecessary 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?

Given no output schema and 0% schema description coverage, the description is incomplete. It does not describe the output format (e.g., list of visitor names, IDs, scores), nor does it provide sufficient detail on parameters or behavioral transparency. The tool is simple but lacks necessary 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 0%, so the description must explain parameters. It does not mention the 'site' or 'limit' parameters at all. The agent has no guidance on what 'site' refers to or how 'limit' affects results. This is a critical 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 it returns 'top high-intent visitors currently active', which is a specific verb+resource. The title reinforces this. It distinguishes from sibling 'eyepup_visitor' by focusing on high-intent and current activity. The example natural language queries further clarify 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 lists example user queries ('who's hot', 'who's about to convert', 'who should I focus on') that trigger this tool, providing clear when-to-use guidance. This is direct and helpful for an agent.

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