Hunter-Seeker

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

Annotations declare readOnlyHint and idempotentHint, and the description adds non-redundant behavioral context: the one-hour cache of ranking_ref, null-statistic semantics ('null means the engine did not report it'), and that an empty driver_group is a real result. These details go beyond the annotations and do not contradict them.

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 dense but front-loaded with the key fact ('Free; no engine run') and then logically flows from purpose to returns to best-for to mistakes. It is verbose – a wall of text – but every sentence contributes value given the tool's risk of misuse. A bulleted structure would earn 5.

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 only two parameters and a documented output schema, the description covers all relevant context: cost, return fields, usage intent, and critical caveats that an agent must know (driver-group semantics, null handling, caching). No obvious gaps remain.

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 already documents both parameters, and the description adds meaningful nuance: format='markdown' yields prose with identical numbers, and ranking_ref must come from a recent hs_rank_topk result (one-hour cache). This compensates the simple schema with context the schema lacks.

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 specifies a concrete action – return a PORTABLE BRIEF from a prior hs_rank_topk result – and clearly distinguishes the tool from siblings by framing it as a single artifact replacing three separate calls. The verb 'return' plus the resource (ranking_ref) makes the purpose unmistakable.

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 'Best for' section lists three explicit use cases (handing analysis to another agent, filing in a store, building a domain expert), and the 'Common mistakes' section provides exclusions and when-not-to-use guidance (e.g., don't compare two briefs for change over time; re-run instead). This is explicit, actionable 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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds important behavioral details: 'Free; no engine run', the leak-guard feature with honest-null vs 'pending', determinism, provenance, and honest-empty. It also clarifies limits, going well beyond the 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 dense and information-rich, but it is written as one long run-on sentence with semicolons. It is front-loaded with 'Free; no engine run' and every clause adds value, but it could benefit from bullet points or shorter sentences for better readability.

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 parameters and no output schema, the description comprehensively covers the return value, use cases, and behavioral guarantees. It explains all the essential aspects a user would need to decide whether to call this tool and what to expect.

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?

With zero parameters, the schema is semantically empty. The description fully compensates by explaining the tool's output contract in detail, listing what will be returned (input contract, problem shapes, trust guarantees, limits, worked examples). This exceeds the baseline 4 for zero-param tools.

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

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

The description clearly states the tool returns Hunter-Seeker's input contract, supported problem shapes, trust guarantees, limits, and worked examples. It explicitly differentiates from siblings by advising to call this first when unsure if a problem is a top-k prediction problem or how to format inputs.

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?

Provides explicit when-to-use guidance: 'Call this first if you are unsure whether a user's problem is a top-k prediction problem or how to format inputs.' This distinguishes it from sibling tools and gives clear context for initial exploration.

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?

Annotations already include readOnlyHint, openWorldHint, and idempotentHint, but the description adds extensive context: it is free with no engine run, reuses the prior analysis, returns engine-authored facts verbatim, never reveals raw arm names or the search objective, and explicitly cautions that drivers are not causal guarantees. It also explains the asymmetric boundary semantics in detail. No contradiction with 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 long but front-loaded with the core purpose and is dense with necessary technical detail about condition semantics. However, it repeats 'no engine run' / 'no new engine run' and 'no extra cost' in multiple places, which adds slight redundancy and prevents a perfect 5.

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 there is no output schema, the description fully covers return fields (pattern.conditions, coverage, lift), explains numeric vs categorical conditions, operator semantics, missing values, and common mistakes. It also provides clear usage boundaries and alternatives, making it complete 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?

The schema already fully documents ranking_ref as 'from a prior hs_rank_topk result', so baseline is 3. The description adds practical guidance on passing the ref verbatim and warns against common mistakes (expired or never-cleared refs), which increases value beyond the schema. It does not invent new parameter semantics, hence 4 rather than 5.

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 that the tool returns the pattern found by Hunter-Seeker for a given ranking_ref, and explicitly distinguishes itself from hs_explain_levers by noting it is not for per-entity 'what would change' questions. The verb 'return' and the specific resource (pattern from ranking_ref) are precise and 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 provides explicit 'Best for' and 'Not recommended for' sections, naming the alternative tool (hs_explain_levers) and explaining when to use each. It also states the prerequisite of calling hs_rank_topk first and using its ranking_ref verbatim, plus warns about expired or sub-threshold refs.

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?

Beyond the readOnly and idempotent annotations, it discloses return constraints (no raw scores, thresholds, weights), the `association_not_causal` label, and the nuanced behavior of `likelihood_direction` differing for adverse vs desirable outcomes. It also warns about common mistakes in interpretation.

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 detailed and well-structured with categories (Best for, Not recommended, Returns, Common mistakes), but it is somewhat lengthy with some repeated caveats about reading likelihood_direction. It remains focused 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?

Despite the lack of an output schema, the description fully describes the return format (per-entity feature changes, direction, magnitude, likelihood_direction, provenance) and the crucial polarity rule. It also covers prerequisites, exclusions, and usage guidance, making it complete for this 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 input schema already documents both parameters with clear descriptions (ranking_ref from prior ranking, entity_ids from that ranking, max 20). The tool description does not add arg-specific details beyond reasserting the prerequisite, so a baseline score is appropriate.

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

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

The description clearly states the tool's function: compute minimal counterfactual feature changes for entities already ranked by hs_rank_topk. It also distinguishes it from explanation of drivers by emphasizing counterfactual levers and the prerequisite of a prior ranking.

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 includes explicit 'Best for' and 'Not recommended for' lists, and warns against using it for entities not in a prior ranking or for causal guarantees. It also clarifies the prerequisite of a prior hs_rank_topk result.

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

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

The description adds substantial behavioral context beyond annotations: it states 'Free; no engine run,' 'reuses the analysis behind the ranking_ref,' and explains return field semantics including null meaning 'there was no finding.' It also clarifies that outputs are 'validation statistics - never a threshold, weight, score, or arm.' This aligns with readOnlyHint and idempotentHint, with no contradictions.

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 dense and structured, starting with the key 'Free; no engine run' and then logically covering inputs, outputs, best-for, and common mistakes. It is longer than ideal but every sentence adds value, so it earns a high-but-not-perfect score.

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 complexity and the absence of an output schema, the description fully covers all return fields (top_decile_lift, calibration_error, validation, lift_curve, leak_guard), their interpretations, usage context, and caveats. It leaves no significant gaps for an agent to invoke it 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?

Although schema coverage is 100%, the description enriches the single parameter ranking_ref by specifying it must come from hs_rank_topk, explaining the 'expired or never-cleared' pitfall, and elaborating on how the reference is reused. This goes well beyond the schema's one-line 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 clearly states the tool 'return the model DIAGNOSTICS' for a ranking from hs_rank_topk, with a specific verb and resource. It differentiates from siblings by explicitly referencing the prerequisite hs_rank_topk and emphasizing it returns validation statistics, not scores or ranks.

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: 'Best for: due diligence before acting, a governance / trust check, or a model-quality section in a report.' It also warns against 'passing an expired or never-cleared ranking_ref' and instructs to 'call hs_rank_topk first,' making the usage context and exclusions 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?

Beyond the minimal annotations (readOnlyHint=false, idempotentHint=false), the description richly discloses behavior: cost implications (free call, billable run), response variants (pending vs completed), progress fields (stage, facts_so_far), status_url TTL, and common mistakes. This goes well beyond what annotations provide.

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 dense but every clause serves a purpose—cost, purpose, response format, progress behavior, status_url, and pitfalls. It is slightly long but well-structured and front-loaded with the cost note. No wasted words.

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

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

With no output schema, the description fully covers return values (pending with retry_after_ms/stage/facts_so_far/status_url, or completed envelope), cost, and error-prone scenarios. For a tool with one parameter, this is exceptionally 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 100% for the single parameter 'task_id', which already has a descriptive schema. The description adds value by clarifying that the task can come from 'dataset_id or fetch_url' modes, extending beyond the schema's 'dataset mode' phrasing. This extra context justifies a step above baseline.

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 polls a long-running ranking task started by hs_rank_topk, using a specific verb ('check'/'poll') and resource. It distinguishes itself from sibling tools by explicitly tying it to hs_rank_topk's async mode.

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 provides clear usage context: use this after hs_rank_topk starts an async run. It gives practical guidance like respecting retry_after_ms and not treating 'pending' as failure. Though it doesn't name alternative tools, the context is sufficient for correct use.

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

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

The description goes well beyond the sparse annotations (readOnlyHint=false, destructiveHint=false). It discloses that the operation is free and runs no engine, that dataset runs are async, that direct_upload requires the user to perform a PUT, and that private/cloud-metadata URLs are refused for safety. It also explains the return values (dataset_id, upload_url) and the proxied upload cap. This is rich behavioral context with no contradiction.

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 purpose and key decisions, and it uses helpful line breaks and sections (returns, common mistakes). However, it is quite long (~320 words) and repeats some facts already present in the schema (e.g., direct_upload cap, no row cap). It earns its length for a complex tool but could be tighter with minor edits.

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 moderate complexity, the description covers all necessary operational context: async behavior, two ingestion paths with size limits, safety constraints, polling, and common mistakes. It even explains when the tool is no longer strictly needed (collapsing provide+rank into one hs_rank_topk call). This is a complete and self-sufficient description.

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 input schema already provides thorough descriptions for all three parameters (100% coverage), earning a baseline of 3. The description augments this by contextualizing parameters within the two workflows (e.g., 'fetch_url public https URL', 'direct_upload false opts back into proxied upload_url'), and by clarifying that name is human-readable. It adds meaningful operational context beyond the schema without being redundant.

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 clear verb and resource: 'Register a dataset too large to inline in hs_rank_topk.' It explicitly distinguishes this tool from the sibling hs_rank_topk, noting it is a prerequisite and that hs_rank_topk now accepts inline data/fetch_url directly. The purpose is unmistakable and well-scoped.

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?

Usage guidance is explicit and actionable. It recommends this tool for any real dataset, describes the two modes (upload vs fetch_url) with trade-offs, and provides clear exclusions: 'Not recommended for: genuinely small tables (inline them...); non-https or private/internal URLs (blocked).' It also points to the alternative of using hs_rank_topk directly for common cases. This is exemplary when-to-use/when-not-to-use documentation.

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

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

The description discloses critical behavioral traits not covered by annotations: it costs one monthly run (refunded on honest-empty or error), returns honest-null values (null means no finding, not pending), may flag leakage columns, and can return honest-empty results if the lift bar is not met. This goes far beyond the simple readOnly/destructive hints in annotations and gives the agent a clear picture of the tool's behavior.

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

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

The description is long, but structurally logical: cost warning first, then purpose, usage guidance, return semantics, and common mistakes. Each sentence contributes necessary information for such a complex tool. However, it is somewhat verbose and could be tightened without losing meaning, which prevents a 5.

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 there is no output schema, the description thoroughly explains all return fields and edge cases (top-k, top-decile lift, calibration, validation, provenance, gate_verdicts, leak_guard) and clarifies honest-null semantics. It also covers error/empty-result behavior and quota refund, making the tool's contract complete for an agent.

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?

Although schema description coverage is high (88%), the description adds valuable parameter-level context: it warns against leakage (outcome_column misuse), advises on inline data size limits, and explains how to choose among data source options (rows vs dataset_id vs fetch_url). This adds meaning beyond the schema's already descriptive fields, especially around common mistakes.

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 the specific action: 'Rank the rows of a table by their likelihood of a binary (yes/no) outcome, and return the top-k highest-likelihood entities with calibrated scores.' This is a precise verb+resource+scope statement. It also distinguishes itself from sibling tools by noting it is 'the only tool that does' cost a run, and lists what it is not for (continuous forecasting, no historical outcome, etc.), clearly separating it from other 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 explicitly provides 'Best for' and 'Not recommended for' sections, giving clear when-to-use and when-not-to-use guidance. It also instructs users to route larger data to data.dataset_id or fetch_url, naming hs_provide_dataset and direct_upload as alternatives. This is comprehensive usage guidance that goes beyond mere description.

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