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 does reveal that the action posts publicly and advises confirmation, which is a meaningful behavior. However, it omits other relevant aspects such as authentication requirements, whether the action is reversible, or any side effects on the issue. It is better than nothing but still incomplete for a mutation 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 a single, front-loaded sentence that states the action and the key caveat. There is zero waste, and the critical warning ('confirm first') is included. It is as concise as possible while conveying essential 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?

For a simple mutation tool, the description covers the core action and a notable behavioral note. Since an output schema exists, return values are not needed. The description does not mention error conditions or authentication, but given the tool's simplicity and the presence of a schema, it is largely sufficient. A slight gap is the lack of guidance on the optional repo parameter's behavior, but that is minor.

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 having a clear description (e.g., 'Markdown comment.', 'Repository as owner/name.', 'The issue number.'). The tool description does not add any extra semantic meaning beyond what the schema already provides. Since the schema fully documents the parameters, the baseline of 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 states a clear verb ('Add'), a specific resource ('a comment'), and a target ('an existing issue'). This unambiguously differentiates it from sibling tools like create_issue, list_issues, or search_issues. The purpose is immediately understandable and not a tautology.

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 usage through its clear purpose, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or when-not-to-use conditions. The 'confirm first' is a cautionary note but not a usage guideline. Sibling tools are distinct enough that a misroute is unlikely, but explicit guidance is missing.

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 behavioral burden and does it well. It discloses that double-booking is refused by default, that failures return the conflicts, and that allow_conflict overrides this behavior—details not visible in the schema's static defaults.

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: one clear purpose statement followed by a focused behavioral note. Every sentence earns its place, and the primary 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?

For a create operation with an output schema and no nested objects, this description captures the key non-obvious behavior (conflict refusal) and the way to bypass it. The return format is covered by the output schema, so nothing critical 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?

Schema coverage is 100%, so the baseline is already met. The description adds situational meaning for allow_conflict by framing it as a retry mechanism after a conflict, and it points to find_free_slot for alternative time selection, which is extra context 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 opens with 'Create a calendar event,' a specific verb and resource that clearly distinguishes this from siblings like list_events, delete_event, and create_issue. The follow-up about conflict behavior reinforces its role as the write path for calendar entries.

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 concrete, actionable guidance for the overlapping-slot case: if the call fails due to a conflict, the agent can use find_free_slot to pick another time or retry with allow_conflict=true. It doesn't explicitly rule out other sibling tools, but the context is clear enough for typical use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the key non-obvious trait that creating an issue 'posts publicly' and requires user confirmation. This is substantive, though it doesn't mention permanence or side effects beyond posting.

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 short sentences, each earning its place: the action, the public/confirmation caveat, and body quality guidance. Information is front-loaded with the core purpose first, and there is no filler.

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?

The description covers purpose, consent, public visibility, and body expectations. The schema covers parameter semantics and the output schema exists. A minor gap is that the default repo behavior when 'repo' is null is not explained, but overall the tool can be invoked correctly with the provided 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?

The schema already describes all four parameters (100% coverage), so the baseline is 3. The description adds value by specifying that the body should include enough context for someone outside the conversation to act on it, which gives meaningful guidance for the body parameter beyond the schema's 'Markdown body.'

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 uses a specific verb and resource: 'Open a new issue.' This clearly distinguishes it from sibling tools like list_issues, get_issue, and comment_on_issue, and the added public-posting caveat clarifies the nature of the 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?

The description provides explicit context for when to use this tool: it posts publicly, so 'confirm with the user first.' It also instructs how to format the body. However, it does not explicitly name alternatives or state when not to use the tool, leaving some inference to the 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. The confirmation instruction is useful and indicates the destructive nature of the operation, but the description does not state permanence, side effects, or authorization requirements, leaving some gaps.

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

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

Two short sentences, no filler, with the core action first and the important safety instruction second. 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?

For a simple one-parameter delete tool with an output schema, the description covers the essential action and the required user confirmation. Minor missing context includes irreversible effects or error behavior, but these are not critical for an agent to invoke the tool 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 input schema already documents event_id with 100% coverage: the parameter is described as the id returned by list_events. The description adds no additional parameter meaning beyond saying 'by id', so the baseline score of 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 uses a specific verb ('Delete') and resource ('calendar event') and specifies the method ('by id'). It clearly distinguishes this from sibling tools like list_events and create_event.

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 an explicit prerequisite: confirm with the user before calling. It does not name alternative tools, but the delete action is self-evident and the confirmation requirement supplies a clear when-not-to-call condition.

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 burden of behavioral disclosure. It clearly states the tool is a read-only introspection operation (describing schema), which is useful. However, it doesn't disclose details like whether the output is truncated, how many tables are returned when omitted, or whether it requires any special permissions. The core behavior is transparent enough for a schema-inspection tool, but some edge-case behavior is unspecified.

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 waste. The first sentence states the tool's function and scope, and the second provides a critical usage directive. The imperative 'Always call this before writing SQL' is front-loaded and actionable.

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 introspection tool with one optional parameter and an output schema, the description is nearly complete. It covers what the tool does, when to use it, and the parameter semantics. The only minor gap is not describing the output format in prose, but the output schema exists and the description's directive is sufficient for an agent to use 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?

The schema already documents the single parameter well (table to describe, omit for all tables), and the description reinforces this by saying 'for one table or all tables.' The description adds the crucial context that omitting the parameter means all tables, which aligns with the schema's default null. Since schema coverage is 100% and the description adds a clear behavioral nuance, this is above baseline.

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

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

The description states a specific verb ('Describe') and resource ('columns, types and foreign keys') for either one table or all tables. It clearly distinguishes itself from siblings like list_tables (which lists table names) and run_query (which executes SQL).

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

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

The description explicitly instructs when to use this tool: 'Always call this before writing SQL -- do not guess column names.' This is a clear usage directive that tells the agent to invoke this tool as a prerequisite before run_query, and it implicitly contrasts with list_tables by focusing on schema details rather than table names.

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 behavioral burden. It discloses that results are ordered earliest-first, already-past times are skipped, and slots respect working-hours boundaries. It does not explicitly state that the tool is read-only, but 'Find' and 'Returns' strongly imply it. Missing details about how existing events are considered are minor because 'open slots' conveys that.

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 no wasted words. The core purpose is front-loaded, followed by the most decision-relevant behavioral notes (ordering, past-skipping, and the create_event handoff).

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 7-parameter schema with 100% coverage and an output schema, the description does not need to restate parameters or return formats. It gives the essential workflow and ordering behavior. It could mention the default search horizon and weekend skipping, but those are already in the schema, so the description is adequate.

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 only adds 'given length' and 'working hours', which map to duration_minutes and day_start/day_end. That is useful but not substantial beyond the schema, so the 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 states a specific verb and resource: 'Find open slots of a given length within working hours.' It clearly distinguishes this availability-search tool from sibling event tools like list_events and create_event by focusing on open slots rather than calendar records.

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 gives clear context: return earliest candidates, skip past times, and feed results into create_event. This implies the intended workflow. However, it does not explicitly state when not to use it or name alternatives, so it falls just 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, the description carries the behavioral burden. It does disclose that the tool returns the body of the issue, which is additional context. However, it does not mention potential errors, permissions, or rate limits. For a read tool, this is acceptable but not exhaustive.

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 that immediately conveys the core purpose. No filler or redundant phrases, and the key differentiator ('including its body') 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 the presence of an output schema and the simplicity of the operation, the description is sufficient for an agent to understand what the tool returns. It could mention error handling or use cases more explicitly, but for a straightforward get operation it is complete enough.

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 parameters are well-documented in the schema. The description adds no parameter-specific meaning but also doesn't need to; the schema already clearly explains both repo and issue_number.

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 action ('Fetch one issue') with a clear resource and distinguishes the scope ('in full, including its body'), which sets it apart from sibling tools like list_issues and search_issues that are about listing or finding issues.

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 guidance on when to use this tool vs alternatives is provided. The description implies usage for retrieving a single issue in detail, but does not state when not to use it or when to prefer siblings like list_issues or search_issues.

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 burden of disclosing behavior. It mentions ordering ('earliest first') and implies a read operation, but does not explicitly state that it has no side effects, nor does it cover potential limitations like pagination, timezone handling, or behavior on empty ranges. For a simple read tool this is adequate but not rich.

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 exactly two sentences. The first sentence front-loads the core function and ordering; the second adds usage context. There is zero redundancy or fluff, and every sentence 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?

For a simple list tool with two optional parameters and an output schema, the description covers purpose, usage, and ordering. The schema handles parameter formats, and the output schema presumably documents return structure. It could benefit from an explicit 'read-only' statement, but that is implied by 'list'. Overall, an agent has enough 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?

The schema provides 100% coverage for both parameters, including format (YYYY-MM-DD) and defaults. The description only refers to 'a date range', adding no new parameter-specific detail. Per the calibration baseline, a score of 3 is appropriate when the schema fully documents parameters.

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 specific verb 'List', the resource 'calendar events', and the scope 'in a date range, earliest first.' This clearly differentiates it from siblings like create_event, find_free_slot, and delete_event, which have different purposes. It also explicitly ties to answering calendar questions and pre-scheduling checks.

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: 'Use this to answer questions about what is on the calendar, and before scheduling anything, so you know what is already booked.' It implies read-only usage and when to invoke it, but does not explicitly name alternatives or state when not to use it. Still, the guidance is actionable and sufficient 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 provided, the description carries the full burden, and it usefully discloses non-obvious behaviors: newest-first ordering and the filtering of pull requests returned by the GitHub issues endpoint. It does not discuss pagination, rate limits, or permissions, but the main gotcha is covered.

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 the core purpose and ordering front-loaded and the important PR-filter caveat second. There is no filler or redundant restatement of the schema.

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 low-complexity list operation, the description plus fully documented input schema and existing output schema cover what an agent needs: target repository, filters, limits, and the key behavioral surprise that PRs are excluded. Nothing essential 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the notion of 'repository', but the input schema already documents all four parameters clearly.

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 and resource: 'List issues in a repository' with the sort order 'newest first'. It does not explicitly differentiate from the sibling search_issues, so it misses full sibling-distinguishing credit.

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 PR-filtering note implies a boundary ('Pull requests are filtered out') and gives useful context about what not to expect. However, it does not explicitly say when to use this tool versus alternatives such as search_issues, so usage guidance is implied rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is to list tables, which is inherently read-only, but it does not mention any limitations, pagination, or other behavioral nuances. The existence of an output schema covers return format, so the description is adequate but minimal.

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 concise sentences with no filler. The primary action is front-loaded, and the usage hint is placed second. Every word 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?

For a simple, parameterless tool with an output schema, the description is complete. It explains what it does and when to use it. The only minor gap is not referencing how it relates to describe_schema, but that is not critical for basic 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 tool has zero parameters, and schema description coverage is trivially 100%. Baseline for zero parameters is 4, and the description adds no parameter information because none exists. This 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 and resource: 'List the tables in the workbench database.' It is unambiguous about what the tool does. However, it does not explicitly contrast itself with describe_schema, which might also provide schema-related information, so it lacks sibling differentiation.

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 a clear usage directive: 'Call this first if you do not already know what data is available.' This tells the agent when to use it, but it does not mention when not to use it or any alternatives, such as describe_schema. The guidance is useful but incomplete.

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 and meets it thoroughly. It discloses that reads are enforced by SQLite itself through a read-only connection and an authorizer, that writes/DDL/PRAGMA/ATTACH all fail, that only one statement is allowed per call, and that the result includes column names, rows, and a capped indicator. This is exemplary 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?

The description is compact and front-loaded with the core purpose in its first sentence. Each subsequent sentence adds meaningful detail (enforcement mechanism, return shape) without fluff. It is appropriately sized for a tool of this complexity.

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 SQL query tool with an output schema present, the description is complete. It covers the execution model (read-only, single statement), the failure modes (non-read actions rejected), and the return shape (columns, rows, capped flag). No critical information is missing 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 coverage is 100%, so the baseline is 3. The description's 'Only one statement per call' mirrors the sql schema description ('A single read-only SQL SELECT statement'), and max_rows already carries its own default and purpose. The description adds no parameter semantics beyond 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?

The description begins with a specific verb+resource: 'Run one read-only SELECT against the workbench database.' This clearly distinguishes it from sibling tools like list_tables or create_event, which target specific operations. The added emphasis on read-only SELECT further clarifies its scope.

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 usage: it is the tool for arbitrary read-only SQL queries. However, it provides no explicit guidance on when to use it versus specialized siblings like list_tables or describe_schema, nor does it mention any exclusions. The context is implied but not directly 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?

With no annotations provided, the description carries the full behavioral burden. It conveys that this is a search operation using query syntax, which implies read-only behavior, but it does not disclose details like authentication requirements, rate limits, pagination, or result-size constraints. This is adequate but not rich.

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 very concise: two sentences, with the core purpose first and the scoping advice second. Every sentence contributes useful guidance, and there is no redundant restatement of the name or schema.

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 only two parameters, full schema coverage, and an output schema, the description provides enough context for correct invocation. The main gap is the absence of any mention of authentication or rate limits, but the description's core usage guidance is sufficient for a straightforward 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?

The input schema already documents both parameters with descriptions and an example, so schema description coverage is 100%. The description adds the important scoping recommendation but does not add parameter-level semantics beyond what the schema provides, matching the baseline of 3.

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 searches issues across GitHub using GitHub's query syntax, giving a specific verb and resource. It does not explicitly differentiate itself from sibling tools like list_issues or get_issue, so it stops 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 clear context by advising agents to scope the search with a repo:owner/name qualifier unless the user genuinely wants global results. It gives an explicit 'unless' exclusion but does not name or discuss alternative tools such as list_issues.

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