Utilify

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

With no annotations provided, the description carries full burden. It discloses that it returns current status (pending, confirmed, failed) plus next-step instructions, and requires a prior signup_id. It does not explicitly state that the tool is read-only (no mutations), but the context strongly implies it. A small gap for not confirming non-destructive behavior.

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 thorough but slightly verbose. It front-loads the purpose and example queries, and every sentence adds useful guidance. Could be trimmed slightly, but overall efficiently structured.

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 only one parameter and no output schema, the description covers: when to use, prerequisites, return values (statuses and next-step instructions), and error handling (no signup_id, failed status). It is fully self-contained for an agent to use 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 description coverage is 100% with signup_id already described as 'The signup ID returned by initiate_signup'. The description adds value by explaining the dependency on a prior call and what to do if the user lacks a signup_id, going 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 'Check where a previously-started Utilify signup stands' and provides specific example user queries ('did my electricity signup go through', 'is my power on for move-in day yet'). It distinguishes from sibling tools like initiate_signup by explicitly requiring a signup_id from that prior call.

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 explicit when-to-use scenarios, example phrases, and what to do when prerequisites are missing (no signup_id: tell user no enrollment and offer to start one). It also provides follow-up actions for specific statuses (pending >48h or failed: recommend 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?

No annotations provided, so the description carries the full burden. It discloses that providers not serving the address's TDU will return no plans (important constraint), and outlines the comparison dimensions (price, contract, features, ratings). It does not explicitly mention authentication, but that is commonly understood. Overall, it provides significant behavioral context beyond the bare minimum.

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: it opens with the core purpose, gives concrete usage examples, follows with behavioral/sequencing details, and ends with a clear exclusion. While slightly longer than minimal, every sentence contributes useful information 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?

Given the tool's moderate complexity (2 required parameters, no output schema), the description adequately covers purpose, usage constraints, sequencing, and return dimensions. It does not specify the exact return format, but that is acceptable in the absence of an output schema. Overall, it provides sufficient context for correct 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that provider_slugs should come from a prior search_utility_providers call and that the address is used for TDU-filtered availability. This additional semantics helps the agent use the parameters correctly, raising the score to 4.

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: 'Compare 2–5 Texas utility providers side by side'. It clearly distinguishes itself from siblings such as search_utility_providers (which surfaces candidates) and get_provider_details (individual provider info). Examples further clarify the tool's purpose.

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 when-to-use guidance ('when the user says help me pick between these two...'), when-not-to-use ('Don't use this to compare across utility types'), and sequencing advice ('best after search_utility_providers has surfaced the candidate REPs'). This fully informs the agent's decision.

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, so description carries full burden. It discloses output format (ordered list with status), personalization by tenancy, and handling of rural addresses. Lacks explicit statement of read-only nature but sufficient for agent understanding.

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?

Description is detailed but well-organized; front-loaded with primary function followed by examples and internal details. Slightly verbose but each sentence 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?

Given 3 parameters, no output schema, and no annotations, the description thoroughly covers inputs, behavior, output format, special cases (rural, tenancy), and even suggests next steps. Highly 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%, baseline 3. Description adds meaning beyond schema: 'address' is full address, 'tenancy' shapes checklist and unlocks cross-sells, 'move_date' specifies ISO 8601 format. This adds 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 generates a personalized move-in utility checklist for a Texas address. It distinguishes from siblings by specifying it's the starting tool, with search_utility_providers as the next step.

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 provides example queries and context for use (e.g., 'I'm relocating to Houston') and exclusions (e.g., 'just handle it for me' leads to concierge). Also describes sequencing with sibling 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?

With no annotations, the description fully handles behavioral disclosure. It explains that promotions are TDU-aware (filtered by address) and describes return fields (discount details, expiration, exclusivity). It does not mention safety properties like read-only, but the context suggests an idempotent read operation. Overall, it conveys key behavior without 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 front-loaded with the core purpose and uses multiple sentences to provide necessary details. It is moderately concise; each sentence adds value (purpose, usage examples, behavior, parameter guidance). A small trim could improve conciseness, but the current length is justified by content richness.

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 adequately covers return structure (active promotions, discount details, expiration, exclusivity) and behavioral nuances (TDU-awareness, address requirement). It also hints at limitations (generic list without address). For a tool of this complexity (3 params), 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%, so baseline is 3. The description adds beyond schema by explaining that the address parameter enables TDU filtering (essential for accurate results) and warns about generic output without it. It also clarifies that utility_types and provider_slugs are filters. This extra guidance elevates the score.

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 specifies that the tool retrieves 'current deals, coupons, and exclusive affiliate offers for utilities at a Texas address.' It clearly distinguishes the purpose from sibling tools like compare_providers and search_utility_providers by focusing on promotional offers.

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 examples of when to use the tool ('what's the cheapest electricity deal', 'any promotions for internet') and notes the consequence of calling without an address (returns generic list). It implies usage over sibling tools for promotional needs, but lacks an explicit alternative or when-not-to-use statement beyond the address caveat.

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 behavioral burden. It discloses that omitting zip_code returns statewide catalog, and lists returned data (plans, rates, contract length, fees). While it doesn't explicitly state read-only or error cases, it provides solid transparency for a read operation.

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 purpose, then context, output, parameter nuance, and exclusions. Every sentence is useful, though slightly verbose; could be condensed.

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 two parameters and no output schema, the description is comprehensive. It covers usage context, parameter behavior, return types, and boundaries, enabling an agent to invoke correctly without additional info.

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 value by explaining that zip_code is used for TDU-filtering and that omitting it changes the result set. It also clarifies that provider_slug is the identifier.

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 'Get plans, pricing, and terms for a specific Texas utility provider', using a specific verb and resource. It distinguishes the tool from siblings by explaining it is used after search_utility_providers and not for discovery or comparison.

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 says 'use after search_utility_providers' and provides example user queries. It also warns against using it to discover providers or compare across REPs, naming siblings search_utility_providers and compare_providers as 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 context beyond the destructiveHint annotation, including user-initiation requirement, return values (URL, phone, signup_id), and TDU error handling.

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?

Well-structured with purpose, triggers, returns, and bullet-point caveats. Slightly verbose but front-loaded and clear.

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?

Comprehensive for a mutation tool with no output schema: explains return values, error cases, and tracking via sibling tool. Covers all needed 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 covers all parameters, but description adds value by clarifying provider_id accepts UUID or slug and move_in_date format. Though baseline is 3, the extra context earns 4.

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 starts enrollment with a specific utility provider at a Texas address, and explicitly distinguishes it 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 triggers for when to use (e.g., 'go ahead and sign me up'), when not to use (concierge alternative), and what to do on error (re-run search).

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 description discloses key behavioral traits: routing to installer partners, referral fee, lead ID return, and that Utilify routes leads. It also clarifies contractual boundaries (Texas-only, homeowner only). This complements the openWorldHint annotation by detailing the side effects.

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 front-loaded with the main purpose and examples, and uses numbered caveats for structure. While comprehensive, it is slightly verbose; some sentences could be condensed. But overall well-organized.

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 9 parameters, no output schema, and openWorldHint, the description is exceptionally complete. It explains the return value (lead ID and next steps), partner network, referral fee, and behavioral constraints. No gaps remain for the agent.

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 description coverage, baseline is 3. The description adds meaning beyond schema: it explains the purpose of email/phone as contact requirements, details interest_level enum meanings, and notes cross-field requirement. However, it doesn't explore every nuance of 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 tool's purpose: 'Capture a Texas homeowner's interest in rooftop solar and route to a licensed installer'. It specifies the resource (solar lead), action (capture and route), and includes concrete examples that distinguish it from 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?

The description provides explicit when-to-use conditions (homeowner in Texas mentioning solar), when-not-to (renters, non-TX, mild curiosity), and alternative actions (answer questions first). It also warns against double-calling the same address.

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 full burden. It discloses many behaviors: utility types, tenancy effects, caveats for water (primaryForZip), trash (contractedHauler), propane/septic urban vs rural, TDU-based electricity filtering, and muni utility handling. This fully informs the agent.

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 long but well-structured: starts with purpose, lists utility types, gives examples, then details parameters and caveats. Every sentence adds value, but could be more concise. Appropriate for a complex tool.

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 is provided, but the description covers key return aspects: providers with plan type, cheapest plan rental-friendly, TDU slug. It addresses edge cases (muni utilities, propane/septic in urban areas) sufficiently for agent decision-making.

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 valuable context: address is a full street address, tenancy changes plan preferences and enables solar cross-sells, utility_types filters or omits to get all. Goes 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 it finds utility providers for Texas addresses, lists nine specific utility types, and provides example user queries. It distinguishes itself from sibling tools like compare_providers and get_provider_details by focusing on the search/discovery use case.

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 states when to use (moving to Texas, setting up utilities) and provides concrete example utterances. It does not explicitly state when not to use or compare to alternatives, but the context is clear enough.

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