SaveOnPhone — Cell Phone Plan Comparison

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations by explaining that cost calculations are only performed when complete evidence exists and that catalog-only rows do not infer totals or savings. This meaningfully shapes agent expectations.

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 tight sentences with no filler. The core purpose is front-loaded, and the important cost-calculation caveat is stated compactly 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 annotations cover safety and the output schema exists, the description is largely complete for invocation. The main gaps are the lack of guidance on optional eligibility/current-service parameters, but these are structurally visible in the schema and less critical given the tool's clear comparison purpose.

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 0%, so the description must compensate, but it only indirectly addresses plan_ids via the 'up to five plans' constraint. It does not clarify line_count, eligibility, or current_service_monthly_cents, all of which are meaningful for running the comparison correctly.

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 identifies the tool's purpose: comparing site prices, features, and conditions for up to five plans. It uses a specific verb and resource, and the comparison focus distinguishes it from siblings like get_plan_details or search_plans.

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 makes the intended use clear: compare multiple plans, capped at five. It does not explicitly name alternatives or state when not to use this tool, but the context is strong enough that an agent can infer this is for multi-plan comparison rather than single-plan lookup.

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 declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds useful context by saying the feed is canonical and only published reporting is returned, but it does not describe query matching behavior or pagination.

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?

A single sentence with no filler, front-loaded with the tool's core purpose and scoped to a specific feed. 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?

This is a simple read-only search tool with a robust annotation set and an output schema, so return-value documentation is unnecessary. However, the description lacks explicit input-parameter semantics and alternative routing guidance, making it adequate but not fully 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 description coverage is 0%, so the description carries the burden of explaining query and limit. It gives the search subject area but never explicitly states that query is free-text search input or that limit caps the number of results, leaving important parameter semantics undocumented.

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: finding published consumer wireless reporting in the canonical SaveOnPhone news feed. It clearly distinguishes this article/reporting lookup tool from the sibling plan-focused tools like search_plans and get_plan_details.

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 when to use the tool: when an agent needs published consumer wireless reporting from the canonical SaveOnPhone feed. However, it does not explicitly state when to prefer this over search_plans or other siblings, nor does it provide exclusions.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the exact types of data read (terms, verification status, source evidence, carrier links), which goes beyond the generic title. However, it does not disclose any other behaviors such as error handling, rate limits, or authentication requirements, which would be expected even with annotations present.

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 that states the verb and resource immediately. It avoids any fluff or repetition, with each word contributing to the meaning. No unnecessary details are included, making it highly 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?

Given the tool's simplicity (one parameter, output schema provided, annotations cover safety), the description covers the core purpose and data returned. However, it lacks explicit usage guidance (when to use over siblings) and does not mention any prerequisites or expected behavior beyond the read operation. This leaves an agent without clear selection criteria, so completeness is only partially met.

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 has 0% description coverage for parameters, so the description must compensate. The description implies that plan_id identifies a plan by saying 'a plan's details', which gives basic semantic meaning. However, it does not elaborate on the format, constraints, or potential edge cases (e.g., invalid ID behavior), so the compensation is minimal but sufficient for a single simple integer parameter.

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 the specific verb 'Read' and resource 'a plan's terms, verification status, source evidence and carrier links', clearly defining the tool's function. It distinguishes itself from siblings like search_plans (which searches) and compare_plan_costs (which compares) by stating it retrieves detailed plan-specific data, not a list 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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this is the right tool for retrieving full details of a specific plan, nor does it exclude using it in contexts where siblings might be more appropriate. The 'Read' verb implies it is for detail retrieval, but there is no direct comparison to siblings like search_plans or get_switching_guide.

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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'performs no account actions', which reinforces the read-only nature but is redundant with annotations. It also mentions 'offer and coverage checks', which hints at the content but not at any behavioral traits like error handling or side effects. Since annotations cover safety, this is adequate but not exceptional.

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 sentence that is direct and front-loaded with the action and resource. It contains no filler and efficiently conveys the core 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?

The tool has one parameter and an output schema, which covers return values. However, the description lacks parameter semantics and usage guidance, which are important for correct invocation. While the output schema mitigates some gaps, the lack of explanation for plan_id and when to use this tool makes it only partially 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?

The schema has a single parameter, plan_id, with no description coverage (0%). The description does not explain what plan_id represents or how it relates to the switching guide. Given the lack of schema descriptions, the tool description should compensate, but it fails to clarify the parameter's meaning or expected usage.

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 clear verb ('Read') and a specific resource ('a switching checklist with offer and coverage checks'). It distinguishes itself from siblings by focusing on a checklist with offer and coverage checks, though it does not explicitly name an alternative. It is clear enough for an agent to understand what the tool does.

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 no guidance on when to use this tool versus alternatives like compare_plan_costs or get_plan_details. It does not mention any conditions, exclusions, or scenarios where this tool is preferred. The only hint is the resource type, which is not enough to route an agent reliably.

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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds the scope 'every searchable carrier' and mentions returned data (plan counts, networks), which gives some behavioral context. However, it does not disclose potential performance implications (e.g., large result set) or any other behavioral traits beyond what annotations state. This is sufficient but minimal.

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, information-dense sentence. It front-loads the main action and includes the key output details without any fluff. Every word contributes value, and it is appropriately concise for a tool with no parameters.

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), the presence of an output schema, and rich annotations covering safety and idempotency, the description is complete. It states exactly what is returned (carriers, plan counts, networks) and the scope (all searchable carriers). An agent has all necessary information to decide whether to call this tool and what to expect.

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 tool has zero parameters, so the description naturally adds no parameter-specific meaning. The baseline for zero-parameter tools is 4, and the description adequately covers the tool's purpose without needing parameter details. There is no gap here.

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 verb 'List' and the resource 'carriers', and specifies that it includes plan counts and networks. It is unambiguous about what the tool does, though it does not explicitly differentiate from sibling tools like search_plans or get_plan_details. Since the purpose is specific to carriers, it is clear enough to be distinguished by an agent.

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 when one needs a catalog of carriers, but provides no explicit guidance on when to choose this over sibling tools such as search_plans or compare_plan_costs. There are no exclusions or alternative references, leaving the selection to inference. This is adequate but not thorough.

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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: pagination via next_offset, catalog prices retaining original dates and conditions, verified_only limiting results to detailed billing evidence, and catalog-only results not establishing confirmed savings. These disclose nuances beyond the structured 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 three sentences, each earning its place: purpose with filter dimensions, pagination and price provenance, and verified_only vs. catalog-only caveat. There is no redundancy or fluff, and the core search function is front-loaded.

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 complex tool with a nested criteria object (14 fields) and zero schema descriptions, the description covers the main search dimensions, pagination, and the important catalog/verified caveat. It does not fully define all parameter formats or explain every filter, but the presence of an output schema and the concise caveats make it largely usable.

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 0%, so the description must compensate. It adds meaning for several key filters (carrier, name/query, network, budget/max_monthly_cents, data/min_data_gb, verified_only) but leaves many criteria fields (age, autopay, bundles, line_count, new_customer, max_prepay_months, etc.) unexplained. This is partially compensating but not fully.

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: 'Search all published plans' and enumerates filter dimensions (carrier, name, network, budget, data). This clearly distinguishes it from siblings like get_plan_details (specific plan retrieval), compare_plan_costs (comparison), and list_carriers (carrier listing).

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 for finding plans matching criteria, but it provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like get_plan_details or compare_plan_costs. Usage context is only implied by the verb 'search'.

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