KnownGate

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

Beyond the readOnlyHint=true annotation, the description discloses crucial behavior: the exact four-verdict enum (no_conflict_found, conflict_found, ask_one_question, couldnt_verify), the return payload shape (typed hits, source kind, read date), the auth requirement, and the semantic guardrails 'Unknown counts as no' and 'safe is never used.' These prevent agents from misinterpreting results — exactly what behavioral transparency should provide.

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

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

Four sentences each earn their place: purpose, auth prerequisite, return contract, and the two critical caveats. The content is dense but organized as a logical progression, front-loading the core purpose before the operational details. Slightly heavy text density prevents a 5.

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

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

For a moderately complex tool with nested objects and no output schema, the description compensates well by enumerating the four verdicts and return fields. Combined with a rich input schema and readOnly annotation, almost everything needed to call correctly is present. Minor omissions like error behavior or rate limits are acceptable at this complexity.

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

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

Schema description coverage is 67%, above the 50% threshold, so the baseline of 3 applies. The schema itself richly documents subject.kind, venue, thresholds, and restrictions; the description adds no parameter-level detail beyond restating the restrictions/thresholds concepts. It neither compensates for gaps nor harms 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 opens with a specific verb+resource pairing — 'Rule one food subject against the household premise' — which precisely scopes the operation to a single food item versus restrictions/thresholds. This clearly distinguishes it from siblings: check_plan (plan-level) and check_venue (venue-level).

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 establishes clear context for when to call this tool ('one food subject') and routes the agent to register for API key creation. It doesn't explicitly name alternatives like check_plan as the 'when-not-to-use' path, but the singleton scope makes the boundary reasonably inferable.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral context: one call returns one verdict per item plus a summary line, and each item carries evidence, source, and read date. It does not contradict the annotations.

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

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

The description is compact, with three focused sentences covering purpose, authentication, limits, and output behavior. It is front-loaded and avoids unnecessary filler, though 'Rule a set of items' is slightly awkward phrasing.

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 batch read tool with no output schema, the description provides essential return-shape context (per-item verdicts, summary line, evidence, source, read date) plus authentication guidance. It could be more complete by mentioning thresholds/restrictions semantics, but the input schema covers those details adequately.

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 does not meaningfully explain the input parameters beyond noting the 25-item cap. The schema already documents items, thresholds, and restrictions reasonably well (67% coverage), but the description itself adds no parameter-level semantic value, such as how thresholds or restrictions should be formatted or chosen.

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 communicates that this tool evaluates or 'rules' a batch of items in a single call, with examples like ingredients, a basket, or several days. It distinguishes itself from singular check_item by emphasizing 'at once,' though it does not explicitly name sibling alternatives.

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

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

It clearly states the batch use case, the 25-subject limit, and the requirement for an API key obtained via register. It gives concrete context for when to use the tool, but it does not explicitly state when not to use it or compare it to check_item/check_venue.

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

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

Beyond readOnlyHint, it discloses the required bearer key, the return payload (counts, severe items, cross-contact caveat, source/read date), and the edge-case behavior for venues without machine-readable charts. These are meaningful behavioral traits not visible in annotations or schema.

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

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

Three sentences front-load the primary action, then cover auth, return contents, and an important edge case. Every sentence adds information without repetition or 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?

Given no output schema, the description usefully enumerates what will be returned and states what happens when a chart is unavailable. Combined with the input schema and readOnly annotation, an agent has enough context to select and call the 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 maps 'venue' and 'restrictions' conceptually but adds little structural detail beyond the schema, which already documents the restrictions array and location. With only 50% schema description coverage, it could have compensated more for the venue object's name field, though the core intent is clear.

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 opening sentence names a specific action—'Rule a whole venue's published chart against the household restrictions'—with a clear resource and scope. The phrase 'whole venue' and 'in one call' distinguishes this from item- or plan-level siblings.

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

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

It gives clear context for use—batch auditing a venue's full chart against restrictions—and even directs users to register for a key. It does not explicitly say when to prefer check_item or check_plan, so it stops short of full exclusion guidance.

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

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

Annotations show readOnlyHint=false and idempotentHint=false, meaning the tool performs a write and is not idempotent. The description adds important behavioral traits: the response contains the key only once ('never shown again') and one key per email, making the non-idempotence concrete. It also clarifies the key's scope (nothing on knowngate.com needs a key), which goes beyond annotations.

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

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

Three concise sentences, each adding distinct value: what it does, limitations/behavior, and scope clarification. Front-loaded with the core purpose, then efficient details. No fluff or repetition of schema properties.

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 2-parameter tool with no output schema, the description covers the essential return value (the key is in the response, never shown again) and the constraints (one per email, free tier). Missing details like rate limits or exact response format are compensated by the explicit 'key is in this response' statement. Sibling tools are check_* functions, so register is clearly the onboarding prerequisite.

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 50%, with contact_email having a description but agent_name only having an example placeholder ('e.g. your product name'). The description adds meaning by explaining contact_email is for contact and recovery, not a wall, which supplements the schema's sparse description. It could have described agent_name more, but the schema's example is adequate.

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?

Description clearly states specific verb ('Sign yourself up') and resource ('developer key'), with additional context about free tier and usage limits. It distinguishes from sibling tools by mentioning 'without leaving MCP' and noting what doesn't need a key.

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?

Description provides clear context for when to use (when user requests a developer key) and implicitly suggests it as a prerequisite for the sibling check tools. It doesn't explicitly name alternatives, but siblings are distinct enough that no exclusions are needed; the 'without leaving MCP' and free tier details help an agent decide.

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