SmartGate

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

The annotations declare readOnlyHint=true, but the description includes an action=record path that logs usage, which is a mutating operation. This is a direct safety-profile contradiction that could mislead an agent about whether the tool is safe to call without write expectations.

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 clearly front-loaded with labeled Purpose, When to use, When NOT to use, Returns, and Composes sections. Every line is short and functional, with no wasted 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?

It covers usage timing, return shape at a high level, and composition, and an output schema exists. However, for a multi-action tool with a mutating record path, the description does not reconcile that behavior with readOnlyHint=true, leaving a significant safety gap.

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 explains the eight parameters in detail. The description only restates the action values and the team_id default behavior, adding little parameter-specific meaning 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 names a specific resource (team token budget) and three concrete actions: check, count, and record. It also distinguishes the tool from general chat/reasoning and from the host model, and it identifies where it composes with smart_fetch/smart_context_gate.

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 states when to use each action: check/count before expensive tools and record after token-consuming work. It also gives explicit when-not-to-use guidance and mentions composition with sibling tools on large jobs.

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 only declare readOnlyHint=true, so the description does real work: it discloses that the optional purpose parameter pre-filters paragraphs by relevance before compression, and that the output is a JSON string with compressed text and ratio metadata. It omits edge-case behavior such as what happens on very short text or failed compression, but for a read-only compression utility the coverage is good.

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?

Uses labeled sections that front-load purpose and usage, and every sentence adds actionable information. Nothing is padded or redundant enough to distract from the key routing signals.

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 three-parameter, read-only compression tool with an output schema, the description covers purpose, usage boundaries, parameter intent, return shape, and composition with downstream/sibling tools. An agent has everything needed 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?

Schema coverage is 100%, so the schema already documents text, ratio, and purpose. The description largely restates those semantics, with only the concrete purpose examples ('API rate limits', 'pricing tables') adding marginal value beyond the schema. Baseline 3 is appropriate when the schema carries 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?

States a specific verb and resource ('Compress long prompts/context') and even names the underlying technique (LLMLingua) plus the timing relative to the host LLM call. An agent can distinguish this from siblings like smart_fetch or smart_search because the description clarifies it operates on already-available text.

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' (context too large, text already available) and 'When NOT to use' (short messages, small context) sections, plus a composing relationship with smart_fetch/smart_search. No inference is required to decide whether this tool is the right choice.

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=true, so safety is covered. The description adds useful behavioral context beyond annotations by disclosing the return shape (kept/removed indices or deduped texts) and placement in a pipeline. It does not mention threshold-driven behavior or edge cases, which keeps it from a 5.

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 structured into Purpose, When to use, When NOT to use, Returns, and Composes with. It is front-loaded and every section adds useful, non-redundant information.

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 two-parameter read-only tool with full schema coverage and an output schema, the description is complete. It covers purpose, usage boundaries, return shape, and composition, leaving no material gap for an agent to call 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that this is semantic rather than exact deduplication, but it adds no additional syntax or threshold guidance beyond what the schema provides. Baseline 3 applies when the schema carries 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 specific verb and resource: semantic deduplication across multiple text passages via SemHash. It clearly distinguishes the tool from siblings by naming composition with smart_search and smart_context_gate, so an agent can identify the right tool without opening the schema.

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 gives both when to use and when NOT to use: overlapping chunks or search results versus a single string or unrelated documents. It also names adjacent tools, making the selection boundary concrete.

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 only supply readOnlyHint, so the description carries the rest and does it well: it flags the 'public' access constraint and warns that the result is a JSON string that must be parsed. It also routes long pages to smart_context_gate. It omits failure modes (timeouts, non-HTML content, truncation) and any rate-limit or auth expectations, which keeps it short of a 5.

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?

Labeled front-loaded lines (Purpose / When to use / When NOT to use / Returns / Composes with) with no filler. Each line conveys a distinct decision-relevant fact, so a scanning agent gets the routing signal in the first sentence.

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 two-parameter read tool with full schema coverage, an output schema, and a readOnly annotation, this covers purpose, routing, return shape, and composition. Missing only edge-case behavior such as what happens on fetch failure or non-text content, which is a minor gap given the output schema exists.

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%, with both url and timeout documented in the schema, so the baseline is 3. The description adds only the 'public HTTP(S)' restriction and says nothing about timeout semantics, so it does not meaningfully exceed what the schema already provides.

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?

Names a specific verb and resource: fetch a public HTTP(S) URL and return Markdown-friendly content. The scope word 'public' and the 'Markdown-friendly content' phrasing distinguish it cleanly from smart_search (which finds URLs) and from reading content already in 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?

Explicitly gives the trigger ('user provides a link and needs the page body or article text'), the exclusions ('full text is already in the conversation, or the target is not a fetchable URL'), and the alternative ('smart_search when no URL yet'). Nothing is left 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?

Annotations only declare readOnlyHint=false, so the description must carry the rest. It does state the return type is action-dependent JSON and that memory is team-scoped and cross-session, but it never says that `delete` is irreversible, that writes persist beyond the session, or how scoping interacts with user_id — the highest-risk behaviors go unstated.

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?

Five labeled lines (Purpose / When to use / When NOT to use / Returns / Composes with) with zero filler and the scoping constraint front-loaded. The exclusion and composition lines each earn their place by preventing a specific misuse.

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 description needn't explain return shapes, and it correctly just flags them as action-dependent. The remaining gap is that only `action` is required, yet the description never says which fields each action demands (e.g., delete needs memory_id, search needs query), leaving room for malformed calls.

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 every parameter including per-action applicability (text for add, query for search, memory_id for get/delete). The description adds nothing about parameters beyond restating the action list, which is the baseline for a fully documented 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?

Opens with a concrete resource and scope ("Team-scoped long-term memory") and enumerates the four supported actions, so the agent knows exactly what surface it operates over. It is distinguishable from smart_fetch/smart_search only indirectly, via the exclusion line, rather than in the purpose statement itself.

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?

Explicit "When to use" (persist/retrieve facts across sessions) and "When NOT to use" (world knowledge, one-off page content → use fetch/search, global encyclopedic answers), plus a named composition partner (smart_search for grounding). This is exactly the routing guidance an agent needs to avoid misusing a memory tool.

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 only readOnlyHint=false, the description adds some real context: it names the return payload ('JSON string with per-step results') and explains how steps compose with the module/smart_* alias. However it says nothing about execution order, failure handling when a step errors, or side effects of the steps it orchestrates — meaningful gaps for an orchestrator that can invoke arbitrary tools.

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?

Labeled sections (Purpose / When to use / When NOT / Returns / Composes with) front-load the decision-relevant information with no filler sentences. Dense but every line carries routing or composition value.

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 return values needn't be explained in depth, and the schema fully covers parameters. Combined with the explicit usage routing and composition note, an agent has what it needs to call it; only step-error behavior is left unaddressed.

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 url/text/query/steps/template are already documented, including the legacy 'args' alias. The description largely restates 'steps[].params (or legacy steps[].args) with tool = module or smart_* alias' without adding new syntax or constraints, so baseline 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?

States a specific verb and resource ('Run a multi-step pipeline') and immediately scopes it to 'built-in template or custom steps'. It distinguishes itself from the smart_* siblings by framing them as the single-step alternative.

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 gives both directions: use when several tools run in sequence (naming the research/read/remember templates), and do NOT use for a single step — call the specific smart_* tool instead. The alternative is named and the selecting condition is stated.

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=true, so the safety profile is covered; the description still adds that results come from multiple engines, are aggregated snippets, and that output is JSON with hits and metadata. It does not mention rate limits, engine variability, or result ordering, so it stops just short of the top marks.

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

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

Four labeled lines, each doing a distinct job, with the routing rule front-loaded ahead of composition notes. The "Returns:" line partly duplicates the existing output schema, which is the only wasted 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 an output schema, full annotation coverage, and only two parameters, everything the agent needs to choose and call the tool is present: purpose, inclusion/exclusion criteria, and downstream composition with smart_fetch and smart_pipe.

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 both query and max_results are already documented (including the 1–50 range and default of 10). The description adds no syntax, quoting, or operator guidance for the query string, so the baseline 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?

States a specific verb and resource ("Run multi-engine web search and aggregate snippets") and contrasts with the sibling smart_fetch by noting the URL condition. An agent can distinguish it from smart_fetch without opening either schema.

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?

Explicit "When to use" and "When NOT to use" lines, and the exclusion names the exact alternative (smart_fetch) plus the condition (user already supplied the exact URL) that selects it. Nothing is left to inference.

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