grok-search

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

No annotations provided, so description carries full burden. It discloses API key masking, a 10-second timeout, and a request to /models endpoint. The read-only nature is implied by 'get' and 'test' and reinforced by the connection-test detail. This is thorough 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?

Well-organized with bold headers and bullet points. The main purpose is front-loaded, and every sentence adds value (features, best-practice usage, behavior). No fluff.

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 parametrized-less tool with no output schema, the description covers what it returns (config, connectivity, models), usage context, and edge cases (timeout, masking). Nothing an agent needs to call and interpret it is missing.

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?

Tool has zero parameters, so baseline is 4. Description adds no parameter meaning because there are none to describe; nothing 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?

States a specific verb+resource: 'Returns current Grok Search MCP server configuration and tests API connectivity.' Lists three concrete features. Unambiguous and clearly distinct from search/fetch/planning 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?

Explicitly recommends 'Use this tool first when debugging connection or configuration issues.' No when-not-to-use or alternative routing given, but siblings are unrelated, so the context is clear.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys this is a read-only retrieval of cached sources, which is inherently safe, and hints that data persists ('cached'). It does not mention what happens for invalid/expired session_ids, auth requirements, or pagination, but for a simple retrieval tool the basic safety profile is adequately conveyed.

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 highly repetitive — three sentences effectively say the same thing: use the web_search session_id to get the source list. It also contains a typo ('invoke the this tool'). A single crisp sentence ('Retrieve all cached sources for a prior web_search call using its session_id.') would carry the full meaning. The redundant first sentence should be cut.

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?

An output schema exists, so the return format is covered externally. For a low-complexity tool with a single required parameter, the description adequately covers when to use it (after web_search) and what it returns (the full source list). The main gaps — error behavior for invalid sessions and any filtering/ordering — are minor given 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% — the schema already documents session_id as 'Session ID from previous web_search call.' The description reinforces that the ID must come from web_search, adding marginal provenance context, but it does not add meaningful syntax or format details beyond what the schema provides. Baseline 3 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 core purpose is clear: 'Retrieve all cached sources for a previous web_search call' states a specific verb and resource, and ties the tool to the web_search sibling via session_id. However, the opening sentence uses odd emotional framing ('When you feel confused or curious...') which muddies the definition rather than clarifying it. The purpose is distinguishable from siblings like web_fetch and web_map because it targets cached search sources.

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 useful context: the tool is invoked with a session_id returned by a prior web_search call, so it is clearly a follow-up to web_search. However, it never states when NOT to use it or names alternatives (e.g., web_fetch for fetching actual page content). The 'confused or curious' trigger is too vague to be 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?

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: the level controls which phases run. However, it does not mention side effects like storing plan state, requiring a session_id from plan_intent, or the ability to overwrite via is_revision. These gaps prevent a higher score.

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 short sentences with zero waste. The phase identification is front-loaded, and the level-to-phase mapping is stated concisely. Every word 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?

Given 8 parameters, no outputs schema, and no annotations, the description is incomplete. It explains the level's impact but does not describe the tool's return value, the requirement for a prior plan_intent session, or how downstream tools use this output. The phase mapping is useful but not sufficient for full contextual understanding.

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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the level parameter's effect on phases (Level 1 = phases 1-3, etc.). This is valuable semantic content not present in the schema's simple 'Complexity 1-3'. Other parameters remain adequately documented by the schema.

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 'Assess' and resource 'search complexity' with an explicit range (1-3). It also identifies itself as 'Phase 2', which differentiates it from sibling tools like plan_intent (Phase 1) and plan_execution (later phase). The mapping of levels to phases adds specificity.

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 by labeling this as 'Phase 2' and explaining that the level 'Controls required phases', implying when it should be called (after plan_intent) and its consequence. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explains the input format for parallel_groups but does not disclose side effects (e.g., whether this overwrites a previous plan when is_revision is true), requirements like authentication, or what the tool does after defining the order. The description is purely about the input syntax, not the 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 a single sentence with zero wasted words. It leads with the purpose ('Phase 6: Define execution order') and immediately provides the critical formatting detail for parallel_groups. The example is compact and directly relevant. This is an appropriately sized, front-loaded 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?

Given the tool has no output schema and no annotations, the description leaves out essential context: what the tool returns, prerequisites (like the session_id provenance), and how this fits into the broader planning flow. It only explains the input format, which is insufficient for an agent to safely and correctly call it without additional assumptions.

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 schema already documents all seven parameters. The description adds a slightly different example ('sq1,sq2;sq3' vs the schema's 'sq1,sq2;sq3,sq4') and restates the semicolon/comma rule, but this is marginal added information. Since the baseline with full coverage is 3, the description meets it but does not elevate beyond the schema.

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 clear verb and resource: 'Define execution order' and identifies it as 'Phase 6' of a planning process. It provides a concrete format example for parallel_groups, which makes the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like plan_tool_mapping or plan_sub_query; the distinction is only implied by the 'Phase 6' context.

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 no explicit guidance on when to use this tool versus alternatives. It does not state preconditions (e.g., 'requires a session_id from plan_intent') or any exclusions. The 'Phase 6' label implies a sequential step, but there is no mention of when this should be invoked or what situations call for a revision.

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 are absent, so the description must carry the burden. It states it creates a session and returns session_id, but does not disclose side effects such as overwriting existing intent (though the is_revision parameter exists in the schema). The description doesn't mention idempotency, revision behavior, or any destructive implications. It's adequate but not fully transparent.

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

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

The description is compact yet information-dense. It front-loads the purpose in the first sentence, then presents the pipeline flow and complexity rules in a clear, scannable format. There is zero redundancy; every sentence contributes necessary context.

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 role in a multi-phase pipeline, the description covers the essential context: it is the entry point, it returns session_id, and it specifies the full flow and complexity-based phase requirements. It does not address the revision use case (session_id revision) that the schema supports, but the schema covers that. Overall it is complete for the typical agent workflow.

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 does not add any parameter-specific meaning beyond what the schema already documents. It doesn't mention any of the input fields (thought, core_question, query_type, etc.) or their roles. Thus it adds no extra value over the schema.

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 the exact purpose: 'Phase 1 of search planning: Analyze user intent' and that it creates a session and returns session_id. It clearly differentiates from sibling tools by being explicitly 'FIRST' in the required flow, which is listed. This is specific 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?

It explicitly says 'Call this FIRST to create a session' and provides the full required flow (plan_intent → plan_complexity → ...). It also gives conditional guidance based on complexity levels (Level 1, 2, 3), which tells the agent when to expect which subsequent phases. This is clear usage guidance with no ambiguity.

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 carry behavioral disclosure. It reveals that calls accumulate data and that the first call must set an approach, which is useful. However, it does not mention critical behaviors like the effect of is_revision (replacing all terms) or what happens on subsequent calls, leaving significant gaps in understanding the tool's side effects.

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 with the core action and usage pattern. It uses two sentences with no filler. While it could be slightly more structured, it is appropriately concise for the information provided.

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 9 parameters (5 required) and no output schema, the description is too minimal. It omits crucial context about the planning workflow, how this tool relates to siblings like plan_sub_query, and what the tool returns. The agent is left to infer many operational details, making it incomplete for reliable 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 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that 'approach' is required on the first call (the schema only has a default), and that 'data accumulates' across calls, which affects how 'term' and other parameters are used. This enhances understanding of the parameters' roles.

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 ('Add one search term') and the resource ('search term'), with a phase context ('Phase 4'). It is specific and not a tautology. However, it does not explicitly differentiate from sibling planning tools like plan_sub_query or plan_intent, so it falls short of a 5.

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 concrete usage guidance: 'Call once per term; data accumulates' and 'First call must set approach'. This tells the agent when and how to call it. However, it does not mention alternatives or explicitly state when not to use it, leaving some inference required about its role relative to other planning 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 available, the description carries the burden of behavioral disclosure. It reveals that data accumulates across calls (stateful) and that is_revision=true replaces all prior sub-queries. This is meaningful behavioral context beyond the schema, though it doesn't cover idempotency or side effects on other planning steps.

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 sentences with zero waste, front-loading the phase and core action. The revision note is efficiently integrated. Every sentence adds value and the structure is easy to scan.

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 10 parameters, 6 required, no output schema, and no annotations, the description covers the essential workflow (accumulation, revision, phase). It doesn't detail the role of session_id or prerequisites, but the schema covers those. It is complete enough for an agent to call the tool correctly in a well-scaffolded planning flow.

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 schema already documents all 10 parameters. The description adds context about is_revision (replace all) which is already in the schema ('True to replace all sub-queries'), so it provides little additional parameter insight. Baseline 3 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 action: 'Add one sub-query' with a specific phase context ('Phase 3'). It also explains the revision alternative ('Set is_revision=true to replace all'), which distinguishes the two modes. This is a specific verb-resource pair that stands apart from siblings like plan_complexity or plan_search_term.

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 usage instructions: 'Call once per sub-query; data accumulates across calls' and the revision behavior. It implies the tool fits into a multi-step planning workflow (Phase 3) but doesn't explicitly name alternative tools for when not to use it. Still, the when/how guidance is clear enough for an agent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only notes 'data accumulates,' which implies state-changing behavior, but omits details about revision (is_revision), side effects, what happens on repeated calls, or any persistence implications. This is minimal disclosure for a stateful 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 two short sentences with no waste. It is front-loaded with the core action and adds a behavioral note. The 'Phase 5' prefix is a bit cryptic without broader context, but overall it is concise and efficient.

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 8 parameters, 5 required, no output schema, and no annotations, the description is insufficiently complete. It explains the basic action but fails to describe how to use the tool correctly, what the 'data accumulates' means for parameters like is_revision, what happens on failure, or any expected return value. An agent would struggle to call this correctly without additional 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 description coverage is 100%, so all 8 parameters are already documented in the schema. The description adds nothing beyond the obvious mapping purpose, so the baseline of 3 is appropriate; the schema handles parameter semantics adequately.

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 clear verb and resource: 'Map a sub-query to a tool.' It also adds a distinguishing behavior ('data accumulates') that helps separate it from siblings like plan_sub_query or plan_execution, though it does not explicitly name alternatives.

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 no explicit guidance on when to use this tool versus alternatives. It mentions 'Phase 5' and 'Call once per mapping,' which hints at a phased workflow, but does not state conditions for choosing this tool over others or any 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 fully carries the burden of behavioral disclosure. It transparently mentions the setting persists to a config file, has immediate effect, and that invalid models can cause later errors. It does not detail any destructive side effects (there are none expected) but covers the key behavioral traits an agent would need 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 with a leading summary, key features, and edge cases. It front-loads the core purpose and organizes supplementary info clearly. It could be slightly more concise (e.g., the 'Key Features' bullet 'Immediate Effect' somewhat repeats persistence info) but remains efficient and scannable.

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 single-parameter tool with no output schema and no annotations, the description is thorough. It covers the operation's purpose, persistence, immediate effect, verification advice, and failure mode. An agent would have everything needed to call it correctly and understand the consequences, so completeness is high.

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 parameter is fully documented in the schema. The description adds general context about what the model affects (search and fetch) but does not provide additional details beyond the schema's already thorough example values. Per the baseline rule, a 3 is appropriate when the schema handles the load.

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 clear action: 'Switches the default Grok model used for search and fetch operations, persisting the setting.' It names the specific resource (default Grok model) and the domain (search and fetch), which clearly distinguishes it from operational tools like web_search or web_fetch. Even without naming a specific sibling, the purpose is 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 'Edge Cases & Best Practices' including 'Use get_config_info to verify available models before switching.' This tells the agent when to use this tool and suggests an alternative for verification. It also warns about invalid model IDs causing API errors and notes persistence across sessions, giving clear practical 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 transparency burden. It discloses that changes apply to the project's .claude/settings.json, that 'status' is non-mutating, and precisely defines the counterintuitive 'on' meaning (block) versus 'off' (allow). While it doesn't mention persistence across sessions or the format of status output, these are minor gaps for a simple toggle 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 a clear opening line followed by 'Key Features' and 'Edge Cases' sections. Every sentence adds value: the action semantics, project scope, status check, and the important clarification that 'on' blocks. It is front-loaded with the core purpose and uses bullets for readability without redundancy.

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

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

For a tool with a single optional parameter, no output schema, and no annotations, the description covers all necessary aspects: functionality, side effects, usage guidance, and edge cases. It even explains the surprising 'on' behavior and how to inspect current state. Nothing essential is missing for an agent to invoke 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?

The schema describes the single 'action' parameter with 100% coverage, including its default and meaning. The description adds contextual guidance on when to use each enum value, but this is practical advice rather than new semantic meaning. Given full schema coverage, baseline 3 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 toggles Claude Code's built-in WebSearch and WebFetch tools, a specific verb+resource. It distinguishes itself from sibling tools like web_search and web_fetch by focusing on enabling/disabling built-in capabilities rather than performing the searches/fetches themselves.

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 'Edge Cases & Best Practices' section explicitly explains when to use each action value ('on' to block when preferring MCP implementation, 'off' to restore native tools, 'status' to check) and clarifies the non-obvious semantics. This leaves no ambiguity about when or how to employ the tool versus 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?

With no annotations, the description carries the full burden. It discloses key behaviors: full content extraction, markdown conversion, 100% content fidelity without summarization, and limitations (dynamic content, large page timeouts). This is useful transparency for a fetch tool, though it does not explicitly state read-only nature or error handling on invalid URLs.

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 with headers and bullet points, front-loading the main purpose. It is concise, though there is minor redundancy between 'Full Content Extraction' and 'Content Fidelity' (both imply completeness). Overall, it is compact and scannable.

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 no annotations, the description explains the return type (structured Markdown) and mentions edge cases (dynamic content, timeouts). However, it lacks explicit differentiation from sibling tools and does not address error handling (e.g., invalid URLs) or whether any side effects occur. It is adequate 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?

The schema already provides a complete description of the 'url' parameter (valid HTTP/HTTPS web address, must be complete and accessible) with 100% coverage. The tool description repeats this accessibility guidance but adds no new parameter semantics, 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 clearly states the action ('Fetches and extracts complete content from a URL') and the output (structured Markdown). It is distinct from web_search (which searches) and web_map (which likely maps links) by focusing on a single URL. The purpose is unambiguous and immediately understandable.

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 its use (when you have a specific URL and want its content) but does not explicitly state when to use this tool over alternatives like web_search. It provides edge cases (accessibility, dynamic content) but no exclusions or routing to siblings, leaving the choice largely to inference.

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 explains the graph traversal approach, depth/breadth controls, instruction filtering, and edge cases like timeout limits ('Large sites may hit timeout limits; adjust timeout and limit parameters accordingly'). This reveals non-destructive behavior implicitly (mapping a site does not modify it) and provides practical limits. It could be more explicit about being read-only, but the overall behavior is transparent 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?

The description is well-structured with clear headings ('Key Features', 'Edge Cases & Best Practices') and bullet points. It is front-loaded with the primary purpose, followed by relevant details. Every sentence contributes to understanding the tool or its usage, with no filler. It is appropriately sized for a tool with 6 parameters and multiple controls.

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 (6 parameters including traversal controls) and the presence of an output schema, the description covers the necessary ground: how it works (graph traversal), how to control it (depth/breadth/limit/timeout), and how to handle edge cases (timeouts, instructions for filtering). It doesn't explicitly mention prerequisites like authentication or public accessibility, but these are not critical for a mapping tool. The output schema covers return values, so that gap is acceptable.

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 value beyond the schema by explaining the purpose of parameters in context (e.g., depth and breadth control under 'Depth & Breadth Control', instructions under 'Instruction Filtering') and giving concrete usage advice like 'Start with low max_depth (1-2) for initial exploration'. This goes beyond the schema's bare descriptions and provides actionable parameter semantics.

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 clear verb and resource: 'Maps a website's structure by traversing it like a graph, discovering URLs and generating a comprehensive site map.' This is specific and distinguishes it from siblings like web_search (searching) and web_fetch (fetching a single page). The mention of 'site map' and graph traversal makes the tool's role 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 best practices for using the tool (e.g., 'Start with low max_depth (1-2) for initial exploration', 'Use instructions to filter for specific content'), which gives practical usage context. However, it does not explicitly state when to use this tool versus alternatives or mention exclusions. There is no reference to sibling tools, so an agent must infer when web_map is appropriate. This is clear context but lacks explicit routing.

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?

Since no annotations are provided, the description carries the full burden. It discloses the native mode calling xAI's Responses API, explains the meaning of sources_count (0 = no retrieval, claims unverified), and introduces search_mode to indicate which path served the request. It also warns about unverified claims when sources_count is 0, providing practical behavioral context beyond the schema.

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

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

The description is well-structured with clear sections and bullet points. It front-loads the primary purpose, then provides usage guidance, and finally explains return fields. Every sentence adds value without redundancy—it's appropriately sized for a tool with 11 parameters and no annotations.

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 11 parameters, no annotations, and no output schema, the description compensates by detailing the return fields (session_id, content, sources_count, search_mode) and their implications, including a connection to the get_sources sibling for full source retrieval. It omits authentication and rate-limit details, but for a read-only search tool this is a minor gap; the essential calling conventions are well covered.

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 only minor clarifications: it restates the purpose of x_handles ('pin the search to specific accounts') and from_date/to_date ('bound it in time') with ISO8601 examples, but these are essentially paraphrases of the schema. No significant new meaning is introduced.

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 identifies the tool as a 'Deep web + X (Twitter) search' with a specific retrieval mechanism (Grok) and structured return format. It distinguishes the X-search capability from general web search, making the purpose unambiguous even without naming a sibling explicitly.

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 for when to reach for this tool: 'X search is the reason to reach for this tool: live community reaction, developer chatter, and breaking discussion.' It implies the primary use case and mentions parameter usage for bounding the search, but it does not explicitly name alternative tools (e.g., web_fetch) or provide 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.