OriginGrid

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

No annotations are provided, so the description bears full responsibility. It reveals admin-only access and token condition, but does not disclose what happens on unauthorized attempt, whether action is reversible, or any side effects. More behavioral detail would improve transparency.

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 one sentence with no unnecessary words. It is front-loaded with the action and resource, and every part adds value—admin restriction and token condition are critical for correct usage.

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 tool with two parameters and no output schema, the description covers the main purpose and prerequisite but omits explanation of contribution_id and the outcome of approval. Given the tool's simplicity, it is adequate but not fully comprehensive.

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 compensate. It only clarifies admin_token's condition but does not explain the required contribution_id parameter. This leaves a significant gap for param 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 'Approve' and the resource 'pending source-card contribution', with additional context of admin restriction and token requirement. It distinguishes from sibling tools like 'reject_contribution'.

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 specifies it is 'admin only' and mentions the conditional requirement for admin_token, giving clear usage context. While it does not explicitly name alternatives, the sibling list and common sense imply when not to use it.

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?

Discloses that the action is anonymous and results in pending review, but does not elaborate on authentication, error states, or return behavior. With no annotations, more detail would be beneficial.

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 efficiently convey purpose and usage context with no extraneous information. The structure is front-loaded and clear.

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?

While purpose and usage timing are covered, the description omits parameter details and response behavior, leaving gaps for a tool with no output schema or annotations.

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?

Parameters have no schema descriptions (0% coverage) and the tool description does not clarify the meaning or usage of 'title' and 'category' beyond their names. No enums or formats are provided.

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?

Clearly states the tool submits a URL as a source-card candidate, specifying it is anonymous and pending review. This distinguishes it from sibling tools like approve_contribution or reject_contribution.

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 guidance on when to use the tool: 'Use AFTER finding a URL that is useful but not yet in the registry.' It does not explicitly mention alternatives or when not to use, but the context is clear enough.

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 behavior. It clearly states the tool uses a local registry without external searches, and optionally narrows by topic/region. However, it does not explicitly state whether the operation is read-only or non-destructive, which would be helpful.

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

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

The description is concise with two sentences plus an actionable ASRP note. It is front-loaded with the core purpose and immediately useful follow-up instructions, with no superfluous 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?

For a discovery tool with no output schema, the description adequately covers the tool's purpose, parameters, and next steps. It lacks details on result format or pagination, but the follow-up tools are referenced. The complexity is low, and the description is sufficient for most use cases.

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 75% (3 of 4 params have descriptions). The description adds context that topic and region are optional filters, but does not provide additional meaning for the 'limit' parameter beyond its schema type and default. The description adds marginal 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 specifies the tool's function as discovering first-hand information sources from the local registry, explicitly stating it does not involve external search engines. It also distinguishes itself from siblings like origingrid_fetch and origingrid_get_source by indicating follow-up actions.

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

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

The description provides explicit guidance on when to use this tool ('FIRST for broad topic discovery') and what to do next ('Follow with origingrid_plan for multi-step fetch or origingrid_fetch for single URL'), including alternatives for different scenarios.

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 fully discloses per-step timeout, automatic retry, error isolation, concurrency limit of 8, and returns structured results with timing.

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-front-loaded with core action, then details. Slightly long but every sentence is informative; could be tightened slightly.

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?

Covers workflow with origingrid_plan, error handling, concurrency, timeouts. Minor gap: does not specify behavior if batch_timeout is exceeded (e.g., partial results).

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

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

Schema covers 100% of parameters, but description adds significant meaning, especially for parallel_groups (concurrency behavior) and retry/timeout defaults.

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 executes multiple search plan steps in batch, distinguishes from siblings by specifying it's used after origingrid_plan, and details the inputs and behavior.

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 says 'Call AFTER origingrid_plan' and explains concurrency management, but does not mention when NOT to use it (e.g., single step use origingrid_fetch).

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 transparency burden. It discloses that the submission feeds source quality signals and explicitly states that rating 3 is neutral, which adds meaningful behavioral context beyond the raw schema. However, it does not describe response behavior or whether feedback can be updated, leaving a minor gap.

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, front-loaded with the primary action and purpose, and includes essential context about the rating scale. Every sentence adds value, and there is no redundant or filler 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?

For a simple feedback submission tool with a comprehensive schema and no output schema, the description is complete. It covers what the tool does, the required identifiers, and the effect on quality signals. No significant missing context is apparent.

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%, with each parameter already described in the input schema. The description adds minimal extra semantics, mostly repeating the origin of search_id and reinforcing the neutral rating. This meets the baseline of 3 for high schema coverage, but does not elevate beyond it.

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 ('Submit feedback'), the resource ('a source returned in a previous search'), and the rating scale (1-5). It distinguishes this tool from siblings by mentioning the use of search_id and its role in feeding quality signals, making it unique among search and contribution 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 provides clear usage context: it is to be used after a search to rate a source, using the search_id from that search. It does not explicitly mention alternatives or when not to use, but the context is unambiguous and distinguishes it from other origingrid 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?

Discloses return structure, caching, and delivery levels. No annotations provided, so description carries full burden; lacks side-effect or auth details but is sufficient for basic understanding.

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 plus an ASRP instruction, all essential. No filler, front-loaded with key 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?

Covers return data shape, parameter usage, and workflow context. No output schema, so description compensates well. Complete for a fetch 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?

Adds meaning beyond schema by explaining return structure, reading guidance, and delivery level usage. Schema coverage is high (83%), but description still enriches 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?

Clearly states 'Fetch first-hand content from a URL' with specific verb and resource. Distinguishes from sibling tools that search, plan, or contribute.

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 instructs to call after origingrid_search and loop over sources, providing a clear use case and workflow integration.

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 bears full burden. It indicates a read operation but lacks details on return format, error behavior, or any side effects. This minimal transparency may lead to agent confusion.

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 that is clear and front-loaded. No unnecessary words; each part serves a purpose.

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 annotations, no output schema, and a single parameter, the description is too sparse. It fails to mention what 'details' are included, potential errors, or any constraints (e.g., requires authentication). Given the many sibling tools, more context is needed for safe 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?

The description adds minimal context ('by its source_id') to the lone string parameter, but the schema already shows it's required. With 0% schema coverage, the description should clarify more about the parameter's format or meaning, which it does not.

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 ('Get details'), resource ('a single information source'), and identifier method ('by its source_id'). This distinguishes it from sibling tools like list or search.

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?

No explicit when-to-use or alternatives are provided. The usage is implied for retrieving a specific source by ID, but there is no guidance for cases like nonexistent IDs or comparisons with similar 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 carries full behavioral disclosure. It explains pagination support (limit/offset, total count), which is good, but does not explicitly state that the operation is read-only or safe, nor mention any authentication or rate limits.

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

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

The description is concise, with two clear sentences and a bracketed usage hint. Every sentence adds value, and the key purpose is front-loaded.

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

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

Given no output schema and low parameter coverage, the description should provide more context. It misses the response structure, what constitutes a 'source,' and how results are identified. The sibling set includes a 'get_source' tool, implying list returns source identifiers, but this is not stated.

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 low (25%: only offset described). The description adds that topic and region are optional filters and that limit/offset control pagination, but it lacks detail on accepted formats, ranges, or allowed values for topic and region.

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 lists available information sources with optional filters by topic and region. It distinguishes from search tools like origingrid_search by framing itself as browsing sources, but does not explicitly differentiate from origingrid_get_source.

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 a usage hint: 'Browse available sources by category. Use for exploration before planning.' This gives clear context, but it does not mention when to avoid using this tool or suggest alternatives like origingrid_search for content.

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. It discloses admin access requirement and conditional token need, and hints at workflow behavior via the review loop. It does not cover error scenarios, idempotency, or response characteristics, leaving gaps for an AI agent.

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 with no wasted words. The first sentence states purpose and access condition; the second provides workflow context. Front-loaded 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?

For a simple one-parameter list tool with no output schema or annotations, the description covers purpose, access constraints, and usage workflow. It omits response structure and failure modes, but these are less critical for such a straightforward 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 description adds context about the admin_token parameter ('requires admin_token when ORIGINGRID_ADMIN_TOKEN is set'), mirroring the schema. It does not explain token format or value constraints. The workflow hint provides marginal extra 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 clearly states 'List pending source-card contributions awaiting admin review' with specific verb and resource. It distinguishes from siblings by specifying 'pending' and 'admin only', but does not explicitly contrast with other list tools like origingrid_list.

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 usage context: admin only, requires admin_token conditionally, and suggests a review loop ('list pending → origingrid_approve_contribution(id)'). However, it gives no explicit guidance on when not to use this tool or alternatives besides the linked approve 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 no annotations, the description fully explains output structure, execution model (agent executes, no caching), concurrency (parallel_group), and a key requirement (browser). Minor omission: no explicit statement about side effects, but the tool appears read-only.

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

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

The description is concise (4 sentences), front-loaded with purpose, and each sentence adds critical value: output structure, execution model, concurrency, browser requirement, and workflow placement. 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?

Given the tool's complexity, 100% schema coverage, and presence of an output schema, the description covers key aspects: output format, execution model, concurrency hints, and a requirement. Minor gaps are possible in error handling but are acceptable for a planning tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add parameter-specific details beyond what the schema provides, meeting the baseline for high coverage.

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 ('Generate') and resource ('executable search plan'), and distinguishes from sibling tools by specifying the workflow position (after search/discover, before origingrid_execute_batch).

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 an explicit [ASRP] directive: 'Call AFTER search/discover. Pass the returned steps to origingrid_execute_batch for concurrent execution.' It also notes a prerequisite ('Requires browser for yellow-difficulty sources'), providing clear context for when to use the 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?

No annotations, so description bears full burden. It mentions admin restriction and optional reason but does not disclose side effects (e.g., notification to contributor, irreversibility) or what happens upon rejection. Adequate but not comprehensive.

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

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

Two sentences, front-loaded with core action and constraints. The second sentence with workflow is slightly list-like but still concise. 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?

No output schema, and description does not mention return value. For a write action, omitting response details is a gap. Also lacks some behavioral context (e.g., permanence). Adequate given sibling tool count but not fully 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 has 3 params with 33% coverage (only reason has description). Description adds minimal context: reason is optional, admin_token needed when env var set. Does not explain admin_token further or contribution_id. Some value added but insufficient given low coverage.

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 specifies the verb 'reject', the target 'pending source-card contribution', and admin restriction. It distinguishes from sibling 'origingrid_approve_contribution' by mentioning the review loop.

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?

States admin-only requirement, conditional admin_token need, and outlines the workflow (list pending then approve/reject). Does not explicitly exclude scenarios but provides sufficient context.

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 provided, so the description carries full burden. It discloses return format (structured JSON with executable_url), supported source types, and exclusions. However, it does not mention error handling, auth requirements, or rate limits, which would be helpful for a complete behavioral profile.

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

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

The description is concise and well-structured: main action first, then return type, source types, exclusions, and usage guidance. Every sentence adds value 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?

Given the tool has 5 parameters (1 required), full schema coverage, and an output schema (so return format is expected), the description is quite complete. It covers purpose, behavior, exclusions, and alternatives. Minor lacking on error handling or permissions but overall sufficient.

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 parameters are already described. The description adds context about source types but does not significantly enhance meaning beyond the schema. 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 resolves natural-language queries into executable source URLs, and it distinguishes itself from siblings like origingrid_plan and origingrid_execute_batch by specifying it is a lightweight alternative for direct resolution. The purpose is specific and actionable.

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 guidance on when to use (direct URL resolution without multi-step plans) and when to use alternatives (for complex queries, use origingrid_plan). Also clarifies what it does NOT do (proxy-fetch or submit to search engines), which prevents misuse.

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 provided, so description carries the burden. It details the return structure and advises against Markdown parsing. Could mention pagination or score meaning, but is largely 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?

Three concise, front-loaded sentences plus an ASRP 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?

Covers most needed context: what it returns, how to handle output, and next steps. Lacks explanation of 'score' and 'difficulty' fields, but overall adequate for a search tool.

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

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

Schema coverage is low (33%) and the description does not explain any parameters. It adds no meaning beyond the schema. With low coverage, description should compensate but does not.

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?

Clearly states 'Search for AI agent information sources' and specifies the return format. Distinguishes from sibling tools like origingrid_fetch (fetching content) and other search variants.

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 instructs to read the array directly without Markdown parsing and to call origingrid_fetch for each source. Includes an ASRP hint providing a step-by-step workflow.

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 full burden. It describes the filtering behavior but doesn't disclose any side effects, auth requirements, rate limits, or output details. For a read-like search tool, this is minimal but not misleading.

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, no fluff. First sentence states purpose with examples; second sentence provides usage guidance. Well structured 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?

Given 3 parameters, no output schema, and no annotations, the description covers the key parameter 'region' and sibling differentiation. Missing details on 'limit' and 'query' behavior, but overall sufficient for a narrow search tool.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains the 'region' parameter with examples and mentions 'query' as optional. However, 'limit' is not described at all. Partial coverage but incomplete.

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 searching sources filtered by region, with examples like cn/global/academic. It distinguishes from sibling origingrid_search by noting it's narrower and for when the target region is known.

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 states when to use (region-specific discovery) and when to use the sibling origingrid_search instead (when region is unknown). This provides clear guidance for tool selection.

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 that the tool generates a plan, persists state across calls, and returns a session_id. This is adequate transparency, though it doesn't mention any side effects, auth requirements, or rate limits.

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, each providing unique value: purpose, output explanation, and usage guidance. It is front-loaded with the core action and has no superfluous content, making it efficient and clear.

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 lack of output schema, the description adequately explains what the tool does, what it returns, and how to proceed. It covers the primary concerns for a session creation tool. Minor missing details like plan specifics are acceptable as they may be covered by sibling tools.

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 describes all 3 parameters with 100% coverage, including default values and constraints. The description adds no extra meaning beyond the schema (e.g., 'Explicit intent override' is already in schema). 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 verb 'Create' and the resource 'search session', specifying it persists across multiple tool calls, generates a plan, and returns a session_id. It explicitly distinguishes from siblings by directing usage instead of origingrid_plan+execute_batch for persistent state.

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: 'Use INSTEAD of origingrid_plan+execute_batch when you need persistent session state across calls' and instructs to call origingrid_search_session_execute with the session_id. This clearly defines when and how to use 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?

No annotations exist, so the description bears full responsibility. It discloses the step execution, result return, and remaining group reporting. It does not cover failure states, rate limits, or idempotency, but the loop pattern is well explained.

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 concise sentences plus a bracketed instruction. No wasted words; 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?

Given no output schema, the description adequately explains return values (results and remaining groups) and the repeat pattern. Lacks error handling or edge case details, but sufficient for basic usage.

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 reinforces the session_id parameter's source but does not add extra meaning to retry_count, step_timeout, or batch_timeout beyond their 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 identifies the tool's purpose: executing the next unexecuted step group in a search session. It differentiates from sibling tools like origingrid_search_session_create by explicitly stating to pass its session_id, and from origingrid_search_session_status by describing the execution action.

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 instructions are provided: call after origingrid_search_session_create, repeat until remaining_groups is 0. This gives clear when-to-use and when-to-stop guidance, effectively distinguishing it from 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 carries the full burden. It implies a read-only operation ('Get'), but does not explicitly state idempotency, side effects, or rate limits. The description of return fields adds some transparency but insufficient for a mutation-free status check.

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 concise sentences plus a bracketed usage hint. Front-loaded with purpose, no redundant or unnecessary 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 no annotations or output schema, the description adequately lists the return fields and usage context. It lacks detail on error handling or session validity, but for a simple status-query tool it is reasonably 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 description coverage is 100% for the single parameter 'session_id', with a clear description in the schema. The tool description adds no additional parameter information beyond what the schema provides, so it meets the baseline but does not add extra value.

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

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

The description clearly states 'Get the current status of a search session' with a specific verb and resource, and lists return fields. It distinguishes from sibling tools like search_session_create and search_session_execute by focusing solely on status retrieval.

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 '[ASRP: Use to check session progress between execute calls.]', providing explicit context on when to use the tool. It does not explicitly mention when not to use it or list alternatives, but the guidance is clear enough for its purpose.

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 provided, so the description must disclose behavioral traits. It only states function and usage order, missing any details on side effects, permissions, rate limits, or whether it is read-only.

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 with zero wasted words. Purpose and usage context are front-loaded 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?

With no output schema, 2 parameters, and no behavioral info, the description is too minimal. It fails to define 'similarity', expected output, parameter details, or error conditions, leaving the agent underinformed.

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%, but the description does not explain 'source_id' or 'limit' beyond the schema. The agent gets no additional meaning about parameter formats, constraints, or sources for IDs.

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 ('Find sources similar to a known source') and includes a usage hint that distinguishes it from siblings like origingrid_search and origingrid_plan.

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 workflow context: 'Use AFTER finding a relevant source to expand your search scope before calling origingrid_plan.' This gives clear guidance on when to use, though it does not mention when not to use or list 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?

Without annotations, the description should disclose behavior. 'Get' implies read-only, but there is no explicit statement about safety, side effects, or output format. Minimal transparency.

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, efficient sentence with no wasted words. It is front-loaded and appropriately sized for the tool's simplicity.

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 zero parameters and an output schema (context indicates it exists), the description is mostly complete. However, it could hint at the kind of statistics provided, though the output schema compensates.

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?

There are zero parameters, and schema coverage is 100% (trivially). The description adds no parameter information, but none is needed. Baseline score of 4 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 retrieves 'OriginGrid registry statistics', specifying the verb and resource. While distinct from siblings focusing on contributions or search, it could be more specific about what statistics are returned.

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?

No guidance is provided on when to use this tool versus alternatives like origingrid_search or origingrid_list. The description lacks exclusions or context for proper tool selection.

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