Utilify

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

Discloses return statuses (pending, confirmed, failed) and next-step instructions, plus branching logic for absent signup_id. Doesn't mention auth or rate limits, but with no annotations, this is still strong.

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 serves a purpose; well-organized starting with purpose, then usage triggers, then error handling – 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 all aspects needed for a simple status-check tool: use cases, input requirements, output behavior, and error recovery – complete given one parameter and no output 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?

Schema coverage is 100% and description adds context beyond the schema by requiring signup_id from a prior call and explaining how to handle missing signup_id, adding 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 the tool checks the status of a Utilify signup, with specific user queries ('did my electricity signup go through') that differentiate it from siblings like initiate_signup or compare_providers.

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 when-to-use guidance with example queries, and handles edge cases like missing signup_id or pending status >48h, including recommending the concierge service.

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 discloses return type (structured comparison across price, contract terms, features, ratings), constraints (TDU-filtered, returns no plans for unsupported providers), and implies read-only behavior. Lacks explicit statement of non-destructiveness.

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 adds value: purpose, examples, sequencing, constraints. Well-structured with no 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?

Covers preconditions (must have searched providers), constraints (2-5, same TDU), and output (structured comparison with specific attributes). No output schema, but description compensates 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?

100% schema coverage provides decent parameter descriptions. The description adds contextual info about provider slugs originating from search results and TDU constraints, but doesn't fundamentally extend parameter meaning.

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 specifies 'Compare 2–5 Texas utility providers side by side', giving a clear verb, resource type, and scope. It distinguishes from sibling tools like search_utility_providers and initiate_signup.

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 usage examples ('help me pick between these two', 'which is cheaper'), sequencing advice (after search_utility_providers), and negative guidance (don't compare across utility types) are 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?

With no annotations, the description carries full burden. It discloses that the tool returns an ordered list of utility tasks with status, tenancy-specific advisories, and rural handling. It doesn't mention side effects or auth needs, but for a read-only checklist generator, this is sufficient.

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 appropriately sized; it is several sentences but every sentence adds value. It is front-loaded with core purpose and use cases, followed by details on behavior and sequencing. 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 complexity (3 params, no output schema), the description is complete. It explains the output (ordered list of utility tasks with status), covers tenancy and rural variations, and provides clear guidance on next steps. It adequately equips an agent to use 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining how tenancy affects the checklist (landlord-handled water/trash for renters, solar-interest for owners) and that rural addresses include propane/septic alternatives. It also clarifies move_date format.

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 generates a personalized move-in utility checklist for a Texas address, with specific verb 'Generate' and resource 'move-in day utility setup checklist'. It distinguishes from siblings by positioning itself as the starting tool and mentioning sequencing to search_utility_providers.

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 use cases (user asks for utilities checklist, step-by-step plan) and examples. It states when to use this tool vs alternatives: 'this is the right starting tool' and directs to call search_utility_providers next. It also handles the 'just handle it for me' case by suggesting the concierge service.

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 carries full burden. It discloses important behavioral details: TDU-aware filtering for electricity, behavior without address (generic list). It lacks mention of authentication or rate limits, but these are not critical for a read-only 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 well-structured, front-loading purpose and usage. While slightly long, every sentence contributes meaning 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?

No output schema exists. The description adequately specifies return content (discount details, expiration, exclusivity). Covers edge cases (with/without address).

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%. The description adds value by explaining the impact of omitting address and how utility_types/provider_slugs narrow results, going beyond the schema annotations.

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's purpose: 'Get current deals, coupons, and exclusive affiliate offers for utilities at a Texas address.' It distinguishes from sibling tools like compare_providers or initiate_signup by focusing on promotions and price discovery.

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 scenarios for use (e.g., 'when the user wants the best available price' and example queries). It implies not to use for general provider comparison but lacks explicit 'when not to use' statements.

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, but description provides behavioral details: returns plans at given ZIP with rates, contract length, fees; explains that omitting zip_code returns statewide catalog rather than buyable options; mentions TDU filtering. Lacks explicit statement that it is a read-only operation, but it's clear from 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?

Three sentences, front-loaded with purpose and usage, then details. Every sentence serves a purpose; 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, so description fully explains return values (plans, rates, contract length, fees, signup requirements). Also covers edge cases (zip_code omission). Complete for its 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?

Schema coverage is 100%, but description adds significant value: explains the critical behavioral difference when zip_code is omitted vs. provided, and clarifies that provider_slug is an identifier. This augments the 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?

Clearly states it gets plans, pricing, and terms for a specific Texas utility provider. Distinguishes from siblings by specifying it should be used after search_utility_providers, not for discovery (use search_utility_providers) or comparison (use compare_providers).

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 when to use (after narrowing with search_utility_providers, when user wants to drill into one option), gives example user queries, and explicitly states when not to use (not for discovery or comparison), naming specific alternative 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?

Beyond the destructiveHint annotation, the description details the tool's behavior: returns a signup URL/phone number or begins API enrollment, produces a signup_id, and provides caveats about user-initiation, TDU errors, and alternative concierge path. No contradiction with 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 well-structured and front-loaded with the purpose and trigger phrases. It is slightly lengthy but every sentence adds value, including caveats and return type. Could be tightened slightly, but remains 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?

Despite no output schema, the description fully explains return values (URL, phone, signup_id) and references check_signup_status for tracking. Addresses error cases and alternative workflows. For a tool with 6 parameters (5 required) and nested objects, the description is comprehensive and leaves no major gaps.

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 adds minimal extra meaning over the schema (e.g., mentions provider_id accepts UUID or slug), but does not significantly enhance parameter understanding 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 clearly states the specific action ('Start enrollment with a specific utility provider at a Texas address') and the context ('use after the user has chosen a plan and confirmed they want to sign up'). It includes concrete trigger phrases and differentiates from sibling tools like check_signup_status and search_utility_providers.

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 when-to-use criteria (e.g., user says 'go ahead and sign me up'), when-not-to-use (point to concierge for manual handling), and alternatives (re-run search_utility_providers on TDU error). Also lists prerequisites (confirm plan, address, move-in date).

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 only include openWorldHint, which is minimal. The description fully compensates by disclosing that it creates a lead, routes to specific installers, may earn referral fee, returns lead ID, and has restrictions (Texas-only, not for renters). No contradictions.

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 slightly lengthy but well-structured. It front-loads the main purpose, then usage examples, then caveats. Every sentence adds value, though some redundancy could be trimmed.

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?

Despite having 9 parameters and no output schema, the description covers the return value (lead ID, next steps), routing logic, restrictions, and opt-in flow. It is comprehensive for the tool's 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 100% with detailed param descriptions. The tool description adds overall context but does not enhance individual 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 clearly states the tool captures a Texas homeowner's interest in rooftop solar and routes to an installer. It uses specific verbs and resources, and the purpose is distinct from siblings which focus on utility providers and signup status.

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 usage conditions are given: when user owns/buying Texas home and mentions solar. Examples are provided. Caveats include opt-in requirement, Texas-only, no double-calls, and when to defer to a follow-up. This clearly guides when to use vs. not 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?

No annotations provided, but the description compensates exceptionally well by detailing TDU filtering, municipal utility behavior, caveats for water, trash, propane, septic, and the effect of tenancy parameter. All behavioral traits are disclosed.

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?

While lengthy, the description is well-structured with clear sections: purpose, utility types, examples, and caveats. Could be slightly more concise, but 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?

Given 3 parameters and no output schema, the description fully covers the tool's behavior, return contents, and edge cases (e.g., municipal utilities, rural alternatives). No gaps identified.

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%, baseline 3. Description adds value by explaining address usage, tenancy impact on plan preferences, and optional utility_types filter behavior, improving beyond 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 states the tool finds utility providers for Texas addresses, covering nine specific utility types. It distinguishes itself from sibling tools like compare_providers and get_provider_details by focusing on search and setup scenarios.

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 usage scenarios with example user phrases. While it doesn't explicitly state when not to use or compare to siblings, the context is clear enough for an agent to determine applicability.

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