KnownGate

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

Although readOnlyHint=true already covers safety, the description goes well beyond that: it discloses the auth requirement, enumerates the four possible verdicts, describes the return contents ('typed hits, source kind and read date'), and clarifies edge-case semantics ('Unknown counts as no; the word safe is never used'). This is rich, non-obvious behavioral context.

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?

Every sentence earns its place: purpose, auth prerequisite, return contract, and key behavioral caveats. The core purpose is front-loaded, and there is no filler or repetition of schema details.

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, the description appropriately discloses return verdicts and result contents. It covers the main invocation needs and key semantics, though it could add a bit more about how verdicts map to downstream decisions or when to prefer a sibling tool. Still, it is sufficiently complete for a well-scoped check operation.

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 67%, so the schema already documents subject kinds, threshold fields, and restriction formats. The description adds useful relationship guidance ('restrictions, thresholds, or both') but does not compensate for the remaining unexplained parameter aspects. It is adequate but not exceptional.

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 ('Rule') and a clear resource ('one food subject against the household premise'), and names the two premise types ('restrictions, thresholds, or both'). It strongly implies a single-item check rather than a plan or venue check, though it does not explicitly name sibling tools to differentiate them.

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: this is for checking one food subject against household restrictions/thresholds, and it states a prerequisite (needs an API key obtainable via register). It does not explicitly say when not to use it or name alternatives like check_plan or check_venue, but the 'one food subject' phrasing provides enough contextual 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 already mark readOnlyHint=true, and the description adds substantial behavioral context: Bearer key auth, the 25-item batch cap, one verdict per item plus a summary line, and per-item evidence, source, and read date. This goes well beyond the annotation without contradicting it.

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 front-load the core purpose before covering auth and output behavior. Every clause contributes useful information 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?

With no output schema, the description still sketches the response shape: one verdict per item, a summary line, evidence, source, and read date. It also covers auth and limits. Exact response formatting and error behavior are left to inference, but the essential guidance is present.

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 item kinds, value constraints, thresholds, and restrictions; the description mainly reinforces the batch size and gives examples of subjects. With schema coverage around 67%, the description adds context but does not meaningfully enrich parameter semantics 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 a specific verb and resource ('Rule a set of items at once') and gives concrete use cases (recipe ingredients, basket, several days). It clearly distinguishes itself as a batch operation from siblings like check_item by emphasizing 'at once' and the 25-subject limit.

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 for when to use the tool: when multiple subjects should be checked in one call. It also notes the auth prerequisite and points to register for creating a key, but it does not explicitly name alternatives or state 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?

Even with readOnlyHint=true, the description adds substantial behavioral context: it requires an Authorization key, summarizes the return payload (per-verdict counts, most severe items, verbatim caveat, source and read date), and honestly discloses the no-machine-readable-chart edge case. This goes well beyond the annotation.

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 focused sentences: the core action, the auth prerequisite, and the return/edge-case behavior. It front-loads the main purpose and every sentence adds useful information without waste.

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 appropriately explains what the tool returns: per-verdict counts, severe items, the cross-contact caveat, and chart metadata. It also covers the no-chart case, auth requirements, and the relationship to the register sibling, making the tool usable without further guessing.

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 restrictions thoroughly, including FDA-9 keys and the optional note object. The description references 'household restrictions' and 'venue's published chart,' but it does not add meaningful syntax or format details beyond what the schema provides, and the venue parameter itself lacks descriptive compensation.

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-resource pairing: 'Rule a whole venue's published chart against the household restrictions in one call.' This clearly distinguishes the tool from siblings like check_item and check_plan by emphasizing whole-venue scope and single-call 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?

The description gives clear context for when to use the tool: when you want to assess an entire venue's chart rather than individual items or plans. It also states the prerequisite of a Bearer key and points to the register tool for obtaining one, though it does not explicitly name when to prefer check_item or check_plan.

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 several behaviors beyond the spare annotations: one key per email, 100 checks/month free tier, the key appears exactly once and is never shown again, and email is used only for contact/recovery. These are meaningful operational facts that help the agent reason about side effects. The annotations (readOnly=false, idempotent=false) are consistent with this.

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 with distinct value: the action, email purpose, key uniqueness/quota/delivery, and the website exception. The purpose is front-loaded and there is no filler or repetition.

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?

Because there is no output schema, the description appropriately states that the key is in the response and shown only once. It also covers the free-tier limit and usage scope. The only notable gap is the behavior on duplicate registration (e.g., whether it errors or returns the existing key), which is ambiguous despite the 'one key per email' note.

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 only 50%: agent_name has a description but contact_email has only format/pattern constraints. The description fills the email gap by clarifying its purpose ('contact and recovery, not a wall') and the one-key-per-email constraint. It adds no new information about agent_name, but the schema already covers that.

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 and resource: 'Sign yourself up for a developer key'. This clearly distinguishes the tool from the sibling check_* tools, which are all lookup/inspection operations.

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 clear context for when the key is needed ('without leaving MCP') and when it isn't ('Nothing on knowngate.com itself needs a key'). It also conveys the free-tier/quota context. However, it does not explicitly name alternative tools or list exclusion conditions, so it falls short of a 5.

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