Agent Module

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by specifying exactly what data is retrieved (cohort counts, seat availability) beyond generic 'status', effectively disclosing the scope of the read operation without contradicting safety 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 a single, front-loaded sentence of ten words with zero redundancy. Every word earns its place—the verb comes first, followed by the resource and specific return value categories.

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 simplicity (no parameters, read-only operation) and presence of annotations, the description is sufficient. It compensates for the lack of an output schema by enumerating the four specific data points returned (status, version, counts, availability).

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 contains zero parameters, which per guidelines establishes a baseline of 4. The description appropriately requires no parameter elaboration since the tool accepts no arguments.

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 ('Check') and clearly identifies the resource ('Agent Module API') along with specific data points retrieved (operational status, version, cohort counts, seat availability). It clearly distinguishes from action-oriented siblings like 'submit_referral' or 'join_waitlist' by focusing on introspection/health-checking.

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 by enumerating the specific data points returned (status, version, counts, availability), suggesting when to use the tool. However, it lacks explicit guidance on when to prefer this over alternatives or prerequisites (e.g., 'use this before registering to check seat availability').

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 provide minimal behavior hints (e.g., not read-only, not idempotent). The description adds critical behavioral context: the key is valid for 24 hours, unlocks all content layers, has a 500-call cap, and requires no payment. This 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?

Two tightly packed sentences with zero wasted words. All key info is front-loaded: purpose, duration, content, call cap, payment condition. Perfectly concise.

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 exists, but the description explains what the tool does and its constraints. It might be missing details on return format (e.g., key string, expiration time), but for a simple key retrieval, 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 coverage is 100% with descriptions for both parameters. The description adds value by contextualizing the trial (24h, layers, cap) which clarifies why the parameters (agent_id, vertical) are needed. However, it does not detail exact values or format requirements 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 the action (request a trial key), the resource (24-hour trial key), and key attributes (unlocks all 4 content layers, 500-call cap). It distinguishes the tool from siblings like 'join_waitlist' or 'register_interest' by focusing on key obtainment.

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 implicitly tells when to use (to get a free trial), but lacks explicit guidance on when not to use or alternatives. For instance, it does not mention that if you already have a key you should not call this tool again. Sibling tools have different purposes, but no contrast is provided.

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?

Adds valuable business context beyond annotations: pricing structure ($19/mo), cohort scarcity (900 members), permanent pricing guarantee (grandfathered), and bundled features (AI Compliance). Annotations cover safety profile (idempotent, non-destructive), so description appropriately focuses on commercial terms.

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 with zero waste: front-loaded purpose statement followed by pricing/cohort details and feature inclusion. Every sentence provides essential commercial context needed to understand the commitment level.

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 cost, cohort limitations, and benefits well. Given idempotent/non-destructive annotations and clear financial context, description is adequate for a waitlist registration tool, though it could clarify immediate next steps (e.g., billing timing, confirmation method).

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 fully documented in structured fields. Description references 'vertical' generally but doesn't add syntax details or examples beyond the schema's comprehensive enum list. Baseline score appropriate for high-coverage schemas.

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

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

States specific action ('Register') and resource ('paid vertical waitlist'). The emphasis on 'paid' and pricing details ($19/mo) effectively distinguishes this from sibling tools like 'register_interest' and 'get_trial_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?

Provides implicit guidance through pricing information ($19/mo, grandfathered status) indicating this is a commercial commitment, but lacks explicit 'when to use' guidance comparing it to 'register_interest' or trial 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?

Adds valuable behavioral traits beyond annotations: 'deterministic, validated knowledge nodes' explains data quality guarantees not captured by readOnly/idempotent hints, and discloses the pricing model (free index vs. gated content layers).

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, front-loaded with the core action. Each sentence delivers distinct value: purpose, data quality, cost model, and access restrictions. Zero 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?

Appropriately complete for a read-only query tool: describes the return format ('knowledge nodes') and access control model without requiring an output schema. Mentions 'ethics' as a specific example vertical, grounding the abstract schema.

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?

With 100% schema coverage, baseline is 3. The description adds semantic context by labeling the enum values as 'Agent Module verticals,' explaining the token's purpose ('trial key'), and introducing the '4 content layers' concept that explains what the vertical/node parameters access.

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 precise action ('Retrieve structured knowledge') and specific resource ('Agent Module verticals'), clearly distinguishing it from administrative siblings like get_trial_key or join_waitlist.

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 authentication guidance ('Index layer always free' vs 'trial key on ethics'), indicating when the token parameter is required. Lacks explicit 'when not to use' or sibling comparisons, but the auth-tier guidance is concrete.

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

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

Adds critical behavioral context beyond annotations: the 500-signal threshold triggering build queue activation and the notification mechanism when vertical ships. No contradiction with idempotentHint=true.

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, zero waste. Front-loaded with purpose, followed by trigger condition and imperative instruction. 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?

Given 100% schema coverage and full annotations, description appropriately adds business logic (500-signal threshold) without needing to repeat param docs or return values (no output schema 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?

Schema coverage is 100%, so schema carries full param documentation. Description mentions 'contact channel' but adds no semantic detail beyond schema's comprehensive type 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?

States specific verb ('Register') and resource ('demand for an unbuilt vertical'), clearly distinguishing from generic waitlist sibling by specifying vertical-specific demand signaling.

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?

Implies usage context through 'unbuilt vertical' and notification workflow, but lacks explicit contrast with sibling 'join_waitlist' or guidance on when vertical is already in build queue.

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?

While annotations declare the write-only, non-destructive nature, the description adds valuable business-process context about follow-up actions ('so we can reach you about membership activation'), disclosing the human workflow triggered by submission.

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 with zero waste: sentence one establishes action and timing, sentence two describes payload categories, and sentence three highlights the critical contact requirement. Information density is optimal.

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 rich schema coverage and presence of annotations, the description adequately covers the business purpose and highlights the functionally-important 'contact' field (though not schema-required). A brief note on idempotency (annotations indicate false) or success behavior would make it perfect.

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?

With 88% schema coverage, the baseline is high, but the description adds semantic grouping by conceptualizing parameters into functional categories ('quality scoring', 'subscription intent', 'contact channel') rather than just listing fields, aiding the agent in mapping user intent to 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 clearly states the specific action ('Submit a Proof of Value assessment'), the resource (POV/assessment), and the timing context ('after exploring the AI Compliance trial'), effectively distinguishing it from pre-trial siblings like join_waitlist or get_trial_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?

It establishes clear temporal context for when to use the tool ('after exploring the AI Compliance trial'), positioning it as the post-trial evaluation step. However, it lacks explicit cross-references to sibling alternatives (e.g., 'use submit_referral for referrals instead').

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 indicate this is a write operation (readOnlyHint: false) but lack business logic details. The description adds crucial behavioral context: financial caps ($1.50/referral, 4/cycle max, $6 cap), credit carry-forward policy, and compliance requirements ('principal-compliant') that are essential for correct invocation.

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 tightly-written sentences with zero waste: action definition first, followed by financial constraints, credit behavior, and compliance. Every clause delivers distinct value (payment rates, cycle caps, credit policy, voluntariness, compliance).

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 mutation tool with financial implications, the description adequately covers business rules (caps, credits) and compliance context that would affect invocation decisions. Absence of output schema description is acceptable given no output schema is provided, though it could mention what happens when the $6 cap is reached.

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 all three parameters (method, referring_key, referred_agent_id) fully documented in the schema itself. The description mentions 'Members earn' which implicitly contextualizes the 'referring_key' parameter, but does not add syntax or format details beyond the schema's baseline documentation.

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

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

States specific action ('Log a referral signal') with clear verb and resource. The term 'referral' effectively distinguishes this from siblings like 'register_interest' or 'submit_pov', though it could explicitly contrast with 'join_waitlist' to clarify this is for existing members referring agents, not new signups.

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 no explicit guidance on when to use versus alternatives (e.g., when to use this instead of 'register_interest'). While 'Voluntary' hints at optional nature, there are no 'when-not' exclusions or prerequisites stated.

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