Spur

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only one behavioral detail beyond that — that the result is the record's full text — and says nothing about error behavior, size limits, or what happens with a stale/invalid id.

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 front-loaded sentence with no filler — the verb and resource come first and the parenthetical id examples follow. Nothing here is redundant or padded.

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 one-parameter, read-only lookup with full schema coverage and no output schema, the description says what goes in and that full text comes out, which is nearly enough. The only missing piece is guidance on how it relates to the record-specific get_* siblings.

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% and the id parameter already documents the 'property:<uuid>' format. The description adds only the enumeration of prefixes (property:, owner:, template:), which is marginally useful but largely restates the schema; baseline 3 applies.

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 a specific verb and resource ('Fetch the full text of a record') and scopes it to records returned by search. However, it never distinguishes itself from the many specific siblings like spur_get_property, spur_get_owner, or spur_get_letter_template, which plausibly return overlapping data for the same id prefixes.

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 phrase 'returned by search' implies the intended workflow (call search, then fetch its id), but this is inference rather than explicit instruction. There is no statement of when to prefer this generic fetch over the record-specific get_* tools, nor any when-not 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the description need not restate safety. It adds that the search scope is the user's saved data and that output ids feed fetch, though it does not mention rate limits or result caps.

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 sentences, front-loaded with the core search action and scope; the fetch handoff and live-listings alternative each add routing value. 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?

For a one-parameter, read-only search with full schema coverage and rich annotations, the description supplies the essential scope and routing. It leaves minor operational details like result limits or mixed-entity grouping unspecified, but these are not critical here.

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 the single query parameter is fully documented in the schema. The description repeats the same keyword categories (address, city, owner name, phone, email, template name) rather than adding syntax or constraints 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 names the specific operation (search), the exact resources (saved properties, owners, postcard templates), the keyword domains, and the return handoff to fetch. It also explicitly distinguishes saved results from live listings via spur_search_properties.

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 says to use this for saved Spur records and to use spur_search_properties for live listings, and it tells the agent that results are ids meant for the fetch tool. This gives clear routing without requiring schema inspection.

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 annotations, the description discloses important behavior: it replaces any existing QR on the card, refuses USPS clear-zone positions, falls back to bottom-right when no QR slot exists, and shows a preview. These details materially help an agent predict the tool's side effects and recovery path.

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 action and remains organized around placement, replacement, and prerequisites. It is slightly dense and long for a tool definition, but nearly every sentence carries useful operational detail for a complex placement operation.

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 six parameters, no output schema, and placement-sensitive behavior, the description covers the key invocation details: prerequisites, fallback placement, rejected zones, replacement behavior, and preview. An agent has enough information to call it correctly without needing further clarification.

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 already 100%, but the description adds real meaning beyond the schema: it explains what `position="auto"` actually targets, how corners and `x_inches`/`y_inches` are interpreted, and why `size_inches` matters for scan reliability. This is substantive parameter guidance, not repetition.

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: put a tracked QR code on the back of the user's postcard template and show the preview. It clearly separates this from QR creation (`spur_create_qr_code`), QR listing, and tracking activity (`spur_get_qr_code_activity`).

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 gives an explicit prerequisite: create a QR code first with `spur_create_qr_code` if `spur_list_qr_codes` has none that fits. It also gives corrective guidance if placement overlaps message text and explains the automatic fallback when no QR slot exists.

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 the full safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's burden is lighter. It adds that the target list must already exist and that only saved properties can be added, but says nothing about duplicate handling, size limits, or what happens on partial failure.

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 front-loaded sentence with zero filler, appropriately sized for a two-parameter tool. It is efficient, though it borders on under-specification rather than optimal density.

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 simple two-parameter mutation with full schema coverage and clear annotations, the description is minimally sufficient. It omits anything about the result of the operation or edge-case behavior (duplicates, invalid list_id), which leaves real gaps for a mutation tool.

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%, and the schema already explains that list_id is a UUID from a Spur list/search tool and that property_ids come from spur_list_saved_properties or spur_save_properties. The description contributes no additional parameter meaning beyond the schema, so the baseline of 3 applies.

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 names a specific verb and resource ("add saved properties to an existing property list"), and the word "existing" implicitly distinguishes it from spur_create_property_list. It does not explicitly name or contrast with any sibling, so it stops short of a 5.

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?

There is no guidance on when to choose this tool over alternatives such as spur_save_properties or spur_create_property_list, nor any prerequisite or exclusion statements. Usage is only inferable from the word "existing."

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 declare destructive=true and non-idempotent, and the description backs that up with concrete consequences the annotations cannot express: immediate switch, prorated charge or credit to the saved card, and a required two-call confirm handshake. It also explains what the free-plan path does differently (billing-portal link rather than an in-place change).

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?

Front-loaded verb-and-resource sentence followed by three bullets, one per branch, each of which carries a distinct decision. No restatement of the title and 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?

For a destructive billing mutation with no output schema, the description covers everything an agent needs: where ids come from, what is returned in each case, what is charged, and when confirmation is required. Nothing material is left to inference.

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 would be 3; the description earns extra by explaining the two-phase use of 'confirm' (call once without to see the exact proration, then again with confirm=true after user approval) and by naming valid plan ids. That is workflow meaning the schema's per-field text does not convey.

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 a specific verb and resource ('Moves the user to another Spur plan') and immediately names the sibling that supplies plan ids (spur_show_billing_options). An agent can distinguish this from spur_manage_billing or spur_show_billing_options without opening any schema.

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?

Gives explicit branching conditions covering the three real states (no paid subscription, already subscribed, moving to free Solo) and the exact confirm protocol for the destructive path. It also routes to the correct prerequisite tool for obtaining plan ids.

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 idempotentHint=true and destructiveHint=false, so 'safe to call repeatedly' largely restates structured data, though it usefully reinforces polling. The description does add what the call yields (new balance and plan), which is valuable given there's no output schema. It does not disclose the important behavioral cases for a payment-confirmation tool: pending/unpaid state, failure handling, or why readOnlyHint is false despite framing this as a 'check'.

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 compact sentence that front-loads the prerequisite, then the action, then the payoff. Nothing redundant or padded.

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?

Without an output schema, the description does convey the return shape (balance and plan), which is a real contribution. However, for a polling-style payment verification tool the key unknown states (not yet paid, failed, expired session) are unaddressed, leaving the agent unsure how to interpret a non-success result.

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% and the single session_id parameter is fully documented there, including the cs_ prefix, so the schema already does the work. The description adds no parameter guidance of its own; baseline 3 applies.

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 a specific verb and resource ('check payment' / confirms payment went through) plus what it returns (new wallet balance and plan). It also names the two sibling tools that produce the prerequisite (spur_top_up_wallet, spur_change_plan), so an agent can place it in the billing flow without ambiguity.

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 states the triggering condition: call it after the user pays a Stripe checkout link from spur_top_up_wallet or spur_change_plan. 'Safe to call repeatedly' further implies a polling pattern. It doesn't state what to do if the payment is still pending or how long to wait, so it stops short of full when/when-not 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 cover the safety profile (readOnly=false, destructive=false, non-idempotent), and the description adds real behavioral facts beyond them: the tool returns an inbox preview, plain text is auto-derived from HTML unless text_body is passed, there is a 50,000-char ceiling, and blank layouts are pre-tested/compliant. It does not say what happens if 'name' collides with an existing template, which is the one visible gap.

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 critical behavior (save + preview) is front-loaded and the three starting modes are a scannable list. The trailing HTML/merge-field guidance is long and reads partly like reference documentation, but it is directly actionable for composing the required payload, so it largely earns its space.

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 an 8-parameter write tool with no output schema, the definition covers creation paths, return behavior (inbox preview), format constraints, validation limits, merge-field syntax, image sourcing, and pointers to spur://email-design-guide and spur://merge-variables. An agent has everything needed to call it correctly on the first attempt.

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 the baseline is 3, but the description genuinely adds cross-parameter meaning the schema cannot: start_from_blank yields a populated layout that html then replaces, base_template_id copies one of the user's own templates, and text_body is only needed when generation should be overridden. The precedence between these three paths is the main thing still unstated.

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?

Opens with a specific verb+resource ('Save a new email template') plus an immediate benefit ('show its inbox preview'), and the three starting modes make the scope concrete. It never explicitly contrasts itself with spur_update_email_template or the SMS/letter/postcard template siblings, so differentiation is left to the name alone.

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 enumerates three explicit entry paths (blank layout, copy via base_template_id, raw html/text_body) with the condition selecting each, and tells the agent the downstream alternatives (spur_create_workflow / spur_set_workflow_step_template) for using the result. Nearly nothing about when to use this vs a sibling is left to inference.

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 declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the real burden and does: it discloses that a preview is rendered, that base_template_id copies HTML and letter type (overridable), and enumerates hard rendering constraints (no scripts, no vh/vw, no box-shadow/transforms, single page margins) that an agent cannot infer elsewhere. This is materially more than the annotations provide.

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?

Purpose and the mode-selection branches are front-loaded and the HTML constraints are bulleted rather than run together, which suits their density. It is long and partially restates material it also points to (spur://letter-design-guide, spur://merge-variables), so a small amount of duplication keeps it from a 5.

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 covers what an agent needs to construct a valid call — modes, layout rules, image URLs, merge fields. It is slightly vague about the outcome: whether the template is persisted on this call or only previewed, and whether an id or preview URL is returned, is implied rather than stated.

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 already 100%, yet the description still adds operational meaning: letter_type is explained in terms of where the address prints and how much page the design can use, with concrete rules per enum value (3.15in blank address zone vs 1.8in letterhead, ~400 words). base_template_id scope is clarified (yours, Spur default, or gallery id) and start_from_blank is described as an empty laid-out page.

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 a specific verb and resource ("Create a letter template") plus an extra behavior ("show a preview"), and the letter-specific vocabulary (address zone, letterhead, letter type) clearly separates it from spur_create_email_template and spur_create_postcard_template. An agent can distinguish it from its siblings without opening the schema.

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?

Gives three explicit entry paths (start_from_blank, base_template_id, raw html) with the conditions selecting each, plus routing to spur_list_images / spur_upload_image / spur_save_image when the user supplies images. It stops short of naming when NOT to use this tool (e.g. spur_update_letter_template for existing templates), so it is strong but not fully exhaustive.

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 annotations, it discloses critical behavior: the tool shows a preview, blank creation can be partially overridden by passing HTML for one side, merge fields are supported, and resending back_html without the qr-box can drop the QR code. That is substantial operational context for a non-readOnly creation 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 front-loaded and well structured with bullets, but it is very long and duplicates substantial design-guide content despite linking to spur://postcard-design-guide. Much of the HTML and USPS clear-zone detail is relevant, but the definition would be tighter if it deferred more to the referenced resource.

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 creation tool with no output schema, it covers the creation modes, HTML sizing, merge fields, image handling, and QR follow-up workflow. It stops short of describing the returned preview format or error conditions, but it is otherwise sufficient to invoke 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?

Although schema coverage is already 100%, the description meaningfully explains parameter interactions: start_from_blank creates an empty sized canvas, base_template_id copies HTML and size, and front_html/back_html override as needed. It also adds size-specific pixel dimensions and constraints not present in the one-line 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 states a specific verb and resource: create a postcard template and show a preview. It immediately distinguishes three creation modes (blank, base_template_id, full HTML), so the agent understands the tool’s scope without opening the schema.

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 gives explicit guidance for each creation path and routes image and QR work to sibling tools like spur_list_images, spur_upload_image, and spur_add_postcard_qr_code. It does not explicitly say when to use this rather than spur_update_postcard_template for modifying an existing template.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds the optional seeding behavior but does not disclose permissions, duplicate-name handling, maximum list size, or what is returned. It adds some useful context but not rich behavioral detail 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?

A single, front-loaded sentence with no wasted words. The primary action is stated first and the optional behavior follows concisely.

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 simple three-parameter creation tool with full schema coverage and annotations covering the safety profile, the description is largely sufficient. It could mention what happens on naming conflicts or that a new list is returned, but no output schema exists and the core behavior is clear.

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 the schema already documents `name`, `description`, and `property_ids` with constraints. The description mentions the optional property-id seeding but adds no syntax or constraints beyond what the schema provides, making the baseline 3 appropriate.

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 ('Create a property list') and adds the optional seeding behavior, making the tool's function clear. It does not explicitly distinguish itself from the sibling `spur_add_properties_to_list`, which handles adding properties to an existing list, but the creation framing is sufficient.

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?

Usage is implied by the verb 'Create' and the optional seeding phrase, but there is no explicit guidance on when to use this versus `spur_add_properties_to_list` or `spur_list_property_lists`. Alternatives and exclusions are left to inference.

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 this is a non-read-only, non-idempotent, non-destructive create operation. The description adds useful behavioral context beyond that: scans are tracked, they route to destination_url, and each mailed postcard can have its own code for per-recipient tracking.

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 short and front-loads the main action in the first sentence. The second sentence usefully explains the next step, though the phrase 'under it' is slightly ambiguous.

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 simple create tool with fully described parameters and clear annotations, the description covers purpose, tracking behavior, and the related postcard workflow. It does not describe the return value, but with no output schema and a straightforward create operation, that omission is not severe.

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 all four parameters are already documented with examples and constraints. The description only repeats that destination_url receives scans and does not add new syntax or selection guidance for name or color 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 states a specific verb (Create) and resource (tracked QR code), and explains the core behavior that scans are sent to destination_url. It also names the related postcard workflow tool, making its role distinct from spur_add_postcard_qr_code.

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 clearly indicates the intended workflow: create the QR code here, then attach it to a postcard with spur_add_postcard_qr_code. It does not explicitly state when not to use it or name alternatives such as spur_update_qr_code, so it stops short of full usage 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 only tell the agent this is a non-idempotent, non-destructive write. The description goes far beyond that: credit costs (1 credit, 2 with >3 ZHomes calls), that auto_enrich spends skip-trace credits every run and should be user-confirmed, and that in automations each event fires once with change events only reporting from the second run. That is exactly the behavioral context annotations cannot carry.

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?

Front-loaded with the core purpose and cost model, then examples, then the event taxonomy — a sensible structure for a 57-parameter tool. It is long, and the event category lists are lengthy, but nearly every sentence supplies information the schema cannot, so little is wasted.

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 57-parameter creation tool with no output schema, the description supplies what the agent needs: the credit model, the recommended preview-then-schedule sequence, event firing semantics across runs, and the notation that 'delisted' is automation-only. Nothing essential to calling it correctly is missing.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: it maps the schema's min_amount/max_amount vs the live-search min_price/max_price, groups the 29 events into lifecycle/distress/valuation categories, and explains the direct-vs-change-event distinction that no enum value conveys. The worked examples show frequency/day_of_week/week_of_month/timezone mapping concretely.

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?

Opens with a specific verb+resource ('Schedule a recurring property search') and immediately distinguishes itself from the live-search and run/list siblings by framing this as scheduling. An agent can tell it apart from spur_run_search_automation and spur_search_properties without opening any schema.

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 prescribes the prerequisite workflow ('Run the search once with spur_search_properties first so the user can check the results before scheduling') and names the sibling it hands off to. It also states when to confirm with the user (auto_enrich) and steers away from listing_type toward events for catching new distress entries.

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 the non-destructive, non-idempotent write profile, and the description adds real behavioral context: the tool returns a phone preview with segment count and checks, messages are billed per segment, and links from unverified numbers can be blocked (justifying fallback_body). None of this is derivable from the annotations or schema.

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 first sentence front-loads the action and its return value, and the second ties the artifact to its consumers. The SMS guidance block is dense but every sentence is actionable (segment limits, opt-out wording, link blocking, merge fields); it is slightly longer than strictly needed for tool selection.

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 describes what comes back (phone preview, segment count, checks). It covers the two required parameters implicitly, names the reference resource for merge variables, and explains the compliance and deliverability rules an agent must satisfy before calling.

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 the baseline is 3; the description goes further by explaining why fallback_body exists (link-free version when a URL causes blocking) and by documenting merge-field syntax like {{owner_first_name}} backed by the spur://merge-variables resource. It does not clarify is_default's interplay with existing defaults, so it is not fully complete.

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?

Specific verb and resource ("Save a new SMS template") plus a disclosure of a side-effect output ("show its phone preview with segment count and checks"). It distinguishes itself cleanly from siblings like spur_update_sms_template and spur_create_email_template, which target different channels or mutation types.

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?

States the downstream purpose by naming the exact consumers (spur_create_workflow / spur_set_workflow_step_template), which tells an agent why it would create rather than fetch a template. However it never explicitly routes away from alternatives such as spur_update_sms_template for edits or spur_preview_message_template for dry-run checks, so there are no stated 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?

Goes well beyond the annotations by disclosing the key behavioral trait: the workflow is persisted as an inactive draft and nothing sends until activation plus owner enrollment. With annotations already declaring non-destructive, non-idempotent write behavior, this is the extra context that matters. It doesn't cover what is returned or duplicate-name 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?

Three tight paragraphs: the draft-status constraint is front-loaded, template sourcing second, and a single worked example last. Every sentence carries actionable information and none is 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?

For a mutating tool with no output schema, it covers lifecycle, template prerequisites, and the branch limitation. The notable gap is that it never says what creation returns (e.g. a workflow id needed to call spur_set_workflow_active or spur_enroll_owners_in_workflow).

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, and the description earns above that by giving a concrete steps example and by mapping each step type to its correct template source (spur_list_message_templates vs. postcard/letter templates). It adds real meaning about step ordering and composition 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?

States a specific verb and resource ('create a multi-step outreach sequence from saved templates') and immediately distinguishes it from the related siblings that activate it (spur_set_workflow_active) and enroll owners. An agent can tell this builds a draft sequencing object rather than sending anything.

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?

Clearly says when to use it (building a send/wait sequence) and notes the prerequisites: templates must exist first, and reply/open/click branches cannot be created here and must be added in the UI afterwards. It does not distinguish this from the adjacent spur_create_search_automation approach or single-send tools, which is the remaining routing gap.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior — that deletion is blocked by template referential integrity — which the agent could not infer from schema or annotations. It does not say how the refusal surfaces (error vs. partial success), which keeps it from a 5.

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-loaded with the action and its permanence, then the failure condition, then the confirmation requirement. No filler or repetition of the title.

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 two-parameter destructive tool with no output schema, the description covers permanence, dependency-based refusal, and the human confirmation requirement — enough to invoke safely. Only the error/refusal mechanics are left unspecified.

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% and both parameters are documented there, including the confirm-only-after-explicit-approval constraint. The description's 'Confirm with the user first' reinforces but does not extend the schema's meaning, so the baseline 3 applies.

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 a specific verb (permanently delete) and a specific resource (one of the user's saved images), which cleanly separates it from the numerous sibling delete tools (delete_qr_code, delete_letter_template, etc.). The word 'permanently' also sets the stakes immediately.

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?

Gives an explicit precondition for failure (refused while postcard, letter or email templates use the image) and an explicit interaction requirement ('Confirm with the user first'). It stops short of naming the sibling to call first (spur_list_images) inside the description, though the schema covers that.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description adds real value beyond them by stating the deletion is permanent, that Spur defaults are protected, and that user confirmation is a required step. It does not say what happens to campaigns or letters already using the template, which is the main remaining unknown for a destructive call.

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, each doing distinct work: what it does, what it can't touch, and the required confirmation step. The permanence warning is front-loaded 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?

For a two-parameter destructive tool with full schema coverage and rich annotations, nothing essential is missing: permanence, the default-template restriction, and the confirmation workflow are all stated. No output schema exists, so no return-value explanation is owed.

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% and the confirm parameter's description already carries the strong 'only after explicit approval' wording, so the description cannot add much. It does implicitly reinforce the confirm gate with 'Confirm with the user first,' but adds no format or sourcing detail for template_id beyond what the schema states. Baseline 3 applies.

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 a specific verb ('Permanently delete') and a precisely scoped resource ('one of the user's letter templates'), which cleanly separates it from the sibling delete tools for message, postcard, QR code, and image resources. It also adds a hard scope boundary: 'Spur defaults can't be deleted.'

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?

Gives an explicit precondition ('Confirm with the user first') and an exclusion (Spur defaults), which is more than most delete tools offer. It stops short of naming alternatives — e.g., that spur_update_letter_template should be used for edits rather than delete-and-recreate — so it isn't a full routing statement.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond structured fields by disclosing the downstream consequence — dependent workflow steps will fail until a replacement template is assigned. It does not say whether deletion is reversible or whether in-use templates are blocked, which keeps it at 4.

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 sentences, zero filler, and the destructive consequence is front-loaded immediately after the purpose. Every clause 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?

For a destructive mutation with no output schema and 100% schema coverage, the description covers the key risk and the required prerequisite check. Minor gaps remain around reversibility and behavior when the template is actively used, but nothing essential to calling it correctly is missing.

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% and the 'confirm' parameter is well documented in-schema (must be true only after explicit user approval). The description's only added signal is the instruction to confirm with the user first, which mildly reinforces the confirm parameter but adds no format or id-value detail beyond the schema. Baseline 3 applies.

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 a specific verb ('Delete') and a precisely scoped resource ('one of the user's email or SMS templates'), which implicitly but clearly separates it from the sibling deleters spur_delete_letter_template and spur_delete_postcard_template. An agent can pick this tool without inspecting either schema.

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?

Gives a concrete pre-flight procedure: check spur_list_workflows and confirm with the user before deleting. That is a clear usage context plus a named dependency tool. It stops short of explicit when-not-to-use conditions or guidance on choosing between deleting vs. updating a template.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds genuine extra context the annotations cannot express: the deletion is permanent, built-in Spur defaults are protected from deletion, and user confirmation is mandatory before invoking. It does not say what the call returns or whether deletion affects campaigns already using the template, which keeps it from a 5.

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-loaded with the action and followed immediately by the two constraints that affect invocation. Nothing is wasted and nothing important is buried.

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 two-parameter destructive tool with full schema coverage and a complete annotation set, the description covers action, eligibility exclusion, and confirmation requirement — enough to call it correctly. No output schema exists, but a delete tool's return value is low-value, so the omission of an explicit statement about the response is a minor gap rather than a blocking one.

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%, and the schema already spells out that template_id is a UUID from a Spur list/search tool and that confirm must be true only after explicit approval. The description's only addition is that default templates are invalid ids, which is marginal. Baseline 3 is appropriate when the schema does all the heavy lifting.

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 a specific verb (permanently delete) and a specific resource (one of the user's postcard templates), and the scope constraint 'Spur defaults can't be deleted' further pins down which templates qualify. An agent can distinguish this from spur_delete_letter_template, spur_delete_message_template, and spur_delete_qr_code purely from the description.

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 an explicit precondition — 'Confirm with the user first' — and an exclusion — Spur defaults cannot be deleted — so the agent knows both a gate and a failure case. It does not name a sibling alternative (e.g., spur_update_postcard_template for non-destructive changes), so it stops short of full when/when-not/alternatives 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 declare destructiveness, idempotency, and non-read-only behavior, but the description adds important operational context beyond them: the deletion is permanent, the tool refuses while postcard templates still print the code, mailed postcards continue redirecting, and explicit user confirmation is required. No contradictions 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?

Four short sentences, each carrying distinct operational value: what it does, the blocking precondition, the side effect on already-mailed postcards, and the confirmation requirement. The core action is front-loaded with no redundant restatement.

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 destructive mutation with no output schema, the description supplies the missing behavioral and procedural context: permanence, refusal condition, required preceding action, and confirmation requirement. Combined with complete annotations and full schema coverage, an agent has everything needed to call it safely.

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 the schema already explains both parameters in detail, including that 'confirm' must only be true after explicit user approval. The description reinforces the confirmation requirement but does not add parameter format or syntax beyond what the schema provides, so the baseline of 3 is appropriate.

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 a specific verb and resource ('Permanently delete a QR code') and immediately distinguishes this operation from related QR-code workflows by naming the sibling tool used when templates still reference it. An agent can identify the action and its scope without opening the schema.

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 the tool will be refused and names the alternative tool to use first ('spur_remove_postcard_qr_code'). It also gives a direct prerequisite instruction: 'Confirm with the user first.' This covers both when to use it and when not to.

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 non-read-only, non-destructive, non-idempotent behavior. The description adds important beyond-annotation context: the tool returns text only, nothing is sent, it consumes 1 AI credit, and merge fields can keep output reusable. These are non-obvious behavioral and cost traits.

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 compact paragraphs: the first front-loads purpose and the critical 'nothing is sent' constraint, while the second covers cost and merge-field reuse. No sentence feels redundant.

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 four-parameter generation tool with no output schema, the description covers output nature (text only), send behavior (nothing sent), cost (1 AI credit), personalization, and merge-field reuse. It does not explicitly state whether the draft is persisted, but that is a minor gap given the annotations and 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, the baseline is 3. The description adds meaning beyond the schema by explaining that owner_id/property_id personalize with real owner and property data, and by documenting merge-field syntax with examples and a related resource.

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 a specific verb and resource: drafting email, SMS, or direct-mail messages with Spur's AI. It distinguishes itself from sending siblings by saying 'nothing is sent,' but does not explicitly differentiate from close siblings like spur_preview_message_draft or template-creation tools.

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 AI-generated draft text is needed and nothing should be sent, but it gives no explicit when-to-use/when-not guidance and does not name alternatives such as previewing a draft or creating a reusable template.

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 destructive=true, openWorld=true, non-idempotent and not readOnly; the description adds key context that enrichment credits are consumed per record and that property_ids creates/links owner records. It does not explain partial-failure behavior or irreversibility beyond the destructive annotation, so it is strong but not exhaustive.

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 short and front-loaded with purpose, then bullets for mode selection, then the cost/approval constraint. Every sentence serves selection or safety.

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 costly, destructive, no-output-schema mutation, it covers the critical preconditions (credit cost, billing check, explicit confirm) and the two input modes. It omits return/result expectations and the mutual-exclusivity or at-least-one rule for property_ids and owner_ids, which are material but not fatal 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 coverage is 100%, so baseline is 3; the description adds real meaning by explaining that property_ids creates/links owner records while owner_ids refreshes existing contacts, beyond the schema's shorter parameter descriptions. It does not clarify whether both arrays may be supplied together or that the schema requires neither, but it improves semantics.

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 names the action (skip tracing/enrichment) and the concrete outputs (phones, emails, mailing addresses), and it separates the property_ids and owner_ids paths. It does not explicitly contrast with sibling tools such as spur_find_owners or spur_get_owner, so an agent must infer that this is the paid enrichment step rather than 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?

It gives the selection rule for each mode: property_ids for saved properties and owner_ids for existing owners, plus a required pre-call approval flow and billing check. It lacks explicit exclusions or a clear statement of whether a discovery tool should be called first, so it is strong but not fully routing.

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 flag destructiveHint=true and openWorldHint=true, and the description goes beyond them by disclosing the real-world consequence: the workflow begins emailing/texting/mailing on its schedule and consumes credits. It omits details like what happens to owners already enrolled or how credits are counted, but the core side-effect disclosure is 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?

Three short sentences, no filler. Purpose first, then the consequence (outreach + credits), then the confirmation requirement — properly 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?

With a fully described 3-param schema, annotations covering safety, and no output schema, the description covers purpose, cost implication, and the confirmation gate. It leaves minor gaps around partial-failure behavior and duplicate enrollment, but nothing critical 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% and the schema itself documents owner_ids provenance, skipping of owners lacking contact details, and the confirm gate. The description only restates 'workflow name and owner count' for confirmation, adding little semantic value beyond the schema; baseline 3 applies.

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?

Clear specific verb+resource: enrolls owner records into an outreach workflow, which is distinguishable from sibling mutations like spur_set_workflow_active or spur_create_workflow. It does not explicitly name a sibling to contrast with, keeping it short of a 5.

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 the right context (after selecting a workflow and finding owners via spur_find_owners) and adds a prerequisite to confirm the workflow name and owner count with the user first. It gives no explicit when-not guidance or alternatives to this tool.

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 readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds the meaningful disclosure that results are summary-level and full details plus portfolio require spur_get_owner. It does not discuss result caps, ranking of matches, or empty-result behavior, which are the remaining behavioral unknowns for a search endpoint.

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 short sentences, zero filler, with the search capability front-loaded and the sibling routing second. Every sentence carries actionable 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?

For a 5-parameter, fully-described search tool with annotations covering safety and no output schema, the description covers purpose, searchable dimensions, and escalation to the detail tool. Only pagination/result-ordering expectations are left implicit, a minor gap given the schema already documents limit and offset.

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%, including the query field's match targets and the limit/offset/filter semantics, so the schema does the heavy lifting. The description restates the query matchable fields but adds nothing about limit, offset, has_phone, or enrichment_status, so baseline 3 applies.

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 a specific verb (Find) and resource (property owners) plus the account scope ('in the user's Spur account') and enumerates the searchable fields (name, phone, email, mailing address). It also distinguishes itself from spur_get_owner, so an agent can pick between the two without opening either schema.

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 routes the agent to spur_get_owner 'for full details and portfolio', which establishes this tool as the lightweight lookup and that one as the detail fetch. It does not say when filtering (has_phone, enrichment_status) is preferable to text query, so usage context is clear but not exhaustive.

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, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds the shape of the payload (counts and errors), but says nothing about ordering, retention window, or behavior when an automation has never run.

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 front-loaded sentence with no filler; the returned fields are packed into one compact clause. Slight redundancy with the title 'Automation run history' but nothing that wastes the agent's attention.

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 two-parameter read tool with full schema coverage and no output schema, the description usefully summarizes what the response contains, which is exactly the gap an absent output schema leaves. Only ordering/retention details are missing, which are minor for a log-listing call.

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 both parameters documented in-schema (automation_id as a UUID from a list/search tool, limit with default 10 and max 50). The description adds no additional meaning about the parameters, so the baseline 3 applies.

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 a specific verb+resource: retrieving recent run history for a search automation, and enumerates the fields returned (timing, found/saved/enriched counts, errors). This clearly separates it from the mutating sibling spur_run_search_automation, though the description never names that sibling explicitly.

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?

Usage is only implied: 'Recent runs of a search automation' suggests post-run inspection, but there is no statement of when to call this versus spur_run_search_automation or spur_list_search_automations, and no mention of prerequisites such as needing a valid automation_id from the list tool.

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=false, establishing the safety profile. The description adds value beyond that by disclosing the shape of the response (plan, wallet balance, per-feature usage and remaining allowance) in the absence of an output schema, though it doesn't state units (dollars vs. credits) or the period boundaries for 'this period'.

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 sentences, no filler, with the payload contents front-loaded and the actionable timing advice second. Every clause 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?

For a zero-parameter read-only tool with no output schema, the description covers the essentials by enumerating returned fields. Minor gaps remain around units, period definition, and how it differs from the billing-mutation siblings, but nothing that would cause a misinvocation.

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 takes no parameters, so the schema carries nothing the description needs to compensate for; baseline applies. The enumerated feature list (searches, enrichment, SMS, postcards, letters, AI) usefully tells the agent what dimensions of data to expect back.

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 enumerates exactly what the tool returns — plan, wallet balance, per-feature usage and remaining allowance for six named channels — so the resource is unambiguous. It does not, however, name or distinguish itself from near-siblings like spur_manage_billing or spur_show_billing_options, which the agent must infer are mutation/option-oriented rather than read-only 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?

"Check this before large sends" gives a concrete triggering condition tied to the costly send operations (send_letters, send_postcards, send_sms). There is no explicit when-not or a named alternative for modifying billing, so it stops short of full routing 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is fully covered. The description adds only that results cover 'delivery and run' statistics, without saying whether stats are live or lagged, whether an unsent campaign returns empty, or what happens for an invalid id — a modest value-add.

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?

One short, front-loaded sentence with no filler. It is efficient but borders on under-specified rather than deliberately tight.

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 simple one-parameter read tool with a fully documented schema and safety annotations, this is minimally sufficient. With no output schema, though, an agent gets no hint about what the statistics contain (counts, rates, time windows), leaving return-value expectations entirely unknown.

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 the single campaign_id parameter is documented there with length constraints and provenance. The description adds nothing about the parameter, which is acceptable given the schema does the work, but earns only the baseline.

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 a specific resource (one campaign) and content (delivery and run statistics), which is more informative than a bare 'get stats'. However, it does not distinguish itself from nearby stats-oriented siblings such as spur_get_property_stats or spur_get_direct_mail_analytics, so an agent must infer the boundaries.

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?

There is no statement of when to use this tool versus list_campaigns, get_direct_mail_analytics, or other reporting tools, and no prerequisites (e.g., campaign must have been sent). The only routing cue, 'UUID from a Spur list/search tool', lives in the parameter schema, not the description.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating which measures are included (in-transit, returned, USPS tracking, spend), which tells the agent what the payload covers. It does not disclose the aggregation window, whether results are account-wide or per-campaign, or any cost/rate considerations — gaps that matter for an analytics read.

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 compact clause with no filler, and the metric enumeration is front-loaded. The only structural weakness is that it is a sentence fragment without a leading verb, which slightly blunts scannability.

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 no-parameter, no-output-schema analytics tool, the description should at minimum state the reporting period and aggregation scope so the agent can interpret the numbers. It names the metrics but leaves the temporal and scoping frame entirely unstated, which is a meaningful gap for a stats endpoint.

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 takes zero parameters, so the baseline is 4. The description does not falsely imply any inputs and does not claim filtering options that the empty schema would contradict.

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 identifies the resource domain (direct mail: letters and postcards) and enumerates the metrics returned (sent, delivered, in transit, returned, USPS tracking, spend), but it is a bare noun phrase with no verb and no statement that the tool retrieves/aggregates analytics. It also does nothing to distinguish itself from siblings like spur_get_campaign_stats or spur_get_outreach_report, which plausibly return overlapping performance data.

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?

There is no guidance on when to call this versus spur_get_campaign_stats, spur_get_outreach_report, or spur_get_billing_summary for spend. No prerequisites, no mention of time scope or filtering expectations, leaving the agent to infer everything from the metric list.

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=false, so the safety profile is fully covered by structured data. The description adds only that the payload is raw HTML and that round-tripping it is expensive, without mentioning size limits or truncation risk for large templates. Useful but thin beyond the 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 sentences, zero filler, with the purpose front-loaded and the cost-saving alternative second. Every clause carries actionable 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?

No output schema exists, and the description does state that the return value is the template's HTML, which is the key unknown an agent would otherwise face. It stops short of noting error behavior for bad ids or bounds on template size for a potentially very large HTML payload.

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% and the single required parameter is documented in the schema itself (UUID or Spur gallery id). The description adds no meaning beyond that, so the baseline 3 applies.

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?

Specific verb+resource: 'Fetch a letter template's HTML' tells the agent exactly what comes back, and the 'reading or editing' framing separates it from the templating-write siblings. It does not, however, distinguish itself from spur_preview_letter_template, which is the nearest ambiguous neighbor in the sibling list.

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 names the alternative (spur_update_letter_template with replacements) and the condition that selects it ('for small text changes'). No exclusion against preview or delete tools, but the primary routing decision is stated outright.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds value by disclosing the exact payload an agent will receive — subject, HTML, plain text, or SMS text — which no output schema provides. It does not cover failure behavior for an invalid or wrong-type template id.

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 written sentences, front-loading what is fetched and what comes back, with the update-vs-fetch routing hint placed second. 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?

For a one-parameter read tool with rich annotations, the description covers purpose, returned content and the editing alternative. Output schema is absent but the return fields are described; only error/not-found behavior is unaddressed, a minor gap.

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 the single parameter is documented in-schema as a template id along with its provenance (from a Spur list/search tool). The description contributes nothing further about the parameter, so the baseline 3 applies.

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 a specific verb (fetch) and resource (email/SMS template) and enumerates the returned fields (subject, HTML, plain text, SMS text), which tells an agent precisely what this yields. It does not explicitly name how it differs from spur_list_message_templates or spur_preview_message_template, so sibling differentiation is implied rather than stated.

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?

Gives clear intent ('for reading or editing') and an explicit routing rule: for small changes use the update tool's replacements rather than resending the whole template. It stops short of saying when to use list or preview instead, so one usage branch is left to inference.

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, idempotentHint and closed-world safety, so the description's burden is lower. It adds the metric set and scope options, but says nothing about aggregation defaults, date-range defaults when omitted, or result size, so it adds value without being rich.

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?

One compact sentence with the metrics and scope front-loaded; every clause carries information. It is a verbless fragment, which is slightly terse but not confusing.

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, so the description partially compensates by listing the metrics returned. However, it leaves unclear what happens with no date range (default window?), whether results are aggregated per channel or per workflow, and what the shape of the response is — gaps an agent may hit on first call.

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 all three parameters are already documented, including the explicit "omit for all workflows" note on workflow_id. The description's "optional date range" restates schema semantics without adding format or defaulting detail, so baseline 3 applies.

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 names a specific resource (outreach report) and enumerates the metrics returned (sent, delivered, opened, replied, by channel), which distinguishes it from siblings like spur_get_campaign_stats and spur_get_direct_mail_analytics by data domain. It stops short of explicitly contrasting those siblings, so a 4 rather than a 5.

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?

"for all workflows or one, over an optional date range" implies the scoping choices an agent has, but there is no explicit when-to-use guidance, no exclusions, and no reference to the analytics siblings an agent might confuse it with.

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 non-destructive behavior, so the safety profile is covered. The description adds useful context that the response is a 'full' record including the property portfolio and enrichment status, which signals payload weight. It does not mention behavior on a missing/invalid owner id.

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?

One front-loaded sentence listing exactly what the record contains, with no filler or 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?

With no output schema, the description usefully enumerates the returned fields, so an agent knows what it gets back. It leaves minor gaps around not-found behavior and whether the embedded portfolio is summarized or full.

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?

Single parameter with 100% schema description coverage, so the schema already explains owner_id format and provenance. The description adds nothing parameter-specific, which is the correct baseline when the schema does the work.

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?

Names the specific resource (owner record) and enumerates the contents returned: contact details, mailing address, enrichment status, and property portfolio. An agent can tell it fetches one owner by id. It does not explicitly contrast itself with spur_find_owners or spur_get_property, so it stops short of a 5.

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 when-to-use guidance, no prerequisites, and no named alternative for looking up an owner. The only hint about source of the id lives in the schema ('UUID from a Spur list/search tool'), not the description.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a workflow-oriented behavioral note about preferring replacements for small edits, which is useful. It does not describe authentication, rate limits, or return-format details beyond what annotations already imply.

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 sentences, both front-loaded and purposeful. The primary operation is stated first, followed by a concise alternative-usage rule. There is no redundant or filler language.

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 simple two-parameter getter with full schema coverage and clear annotations, the description is largely complete. It explains the core action and one important alternative workflow. It could mention that the result is HTML content specifically, but the title and description already imply this.

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 both parameters are already documented in the schema. The description does not add syntax, defaults, or enum meaning beyond what the schema provides. Baseline 3 is appropriate when the schema fully carries parameter semantics.

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 and resource: 'Fetch a postcard template's HTML.' It clearly distinguishes the core operation from sibling update tools by naming spur_update_postcard_template. It does not explicitly distinguish from preview or list siblings, but the purpose is still clear.

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 gives a concrete usage rule: for small text changes, prefer spur_update_postcard_template with replacements instead of resending whole HTML. This names the alternative and the condition for choosing it. It lacks guidance on when to use this versus preview_postcard_template or list_postcard_templates.

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, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds return content beyond that – 'detailed card', 'owner links', 'enrichment status for saved properties' – which meaningfully tells the agent what comes back. It does not say what happens when neither optional identifier is supplied, which is the one real gap.

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?

One sentence, front-loaded with the action and resource, followed by the two identifier modes and the payload highlights. 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 must carry return expectations, and it does name the card format, owner links and enrichment status. Missing only the behavior for the zero-argument case and roughly how much detail the card contains.

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 goes further by mapping each parameter to a distinct meaning (property_id = saved Spur property, zpid = live listing), which clarifies the alternative paths better than the bare schema descriptions do.

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 a specific verb ('Show') and resource ('one property') and distinguishes the two lookup modes: saved Spur property by property_id vs live listing by zpid. This is clearly narrower than list_saved_properties or search_properties, so an agent can pick it without opening schemas.

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 clear which identifier selects which retrieval path ('saved Spur property by property_id, or a live listing by zpid'), which is real usage context. It stops short of naming alternatives or exclusions, e.g. that stats belong to spur_get_property_stats or that zpids come from spur_search_properties.

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 this as a safe, read-only, idempotent, closed-world operation with no destruction. The description adds useful behavioral context by enumerating what the totals cover (status counts, enrichment progress, similar portfolio metrics), but it leaves the exact return shape vague and says nothing about freshness or scoping beyond 'the user's saved properties'.

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 front-loaded sentence that describes the resource and its main aggregate categories. Every clause carries information; there is no padding or restatement of the tool name.

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 zero-parameter, read-only aggregate tool with no output schema, the description gives an agent enough to know it will receive portfolio-level summary counts rather than a list or single record. The only slight gap is that 'similar portfolio-level numbers' is fuzzy, but the key categories are named.

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 input parameters, so there is nothing for the description to explain. The baseline for a parameterless tool applies, and the description correctly does not invent parameter guidance.

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 output: aggregate totals for the user's saved properties, including counts by status and enrichment progress. It distinguishes itself from listing siblings like spur_list_saved_properties and from single-property spur_get_property by emphasizing portfolio-level numbers, though it does not name those alternatives explicitly.

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?

Usage is implied rather than stated: an agent can infer this is the tool for portfolio summaries rather than raw lists or single-property details. However, there is no explicit when-to-use rule or mention of alternatives such as spur_list_saved_properties or spur_get_property.

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 this as a safe, read-only, idempotent operation. The description adds useful behavioral context by describing the shape of the result: totals, which mailed recipients scanned, and recent scans. It does not discuss pagination or limits, but the schema covers the limit parameter.

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 sentences with no wasted words. The return data is front-loaded before the use-case sentence, which is efficient 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?

No output schema exists, but the description explains the main categories of returned data. Annotations cover safety, and the schema fully documents both parameters. Nothing essential for correct invocation is missing.

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 both parameters are already documented in the schema. The description adds no additional meaning about parameter usage or formatting, so the baseline score of 3 is appropriate.

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 a specific verb and resource: retrieve scan activity for a QR code. It also names the three kinds of data returned (totals, recipient-level scans, recent scans), which clearly distinguishes it from siblings like spur_list_qr_codes or spur_update_qr_code.

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 usage context: 'Use it to find warm leads from a postcard campaign.' It does not explicitly name alternatives or when-not-to-use conditions, but the intended use case is clear.

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=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds two real behavioral facts — the result is the complete thread and it is ordered oldest first — but says nothing about volume caps, truncation, or what a message entry contains.

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?

One short clause with zero filler, and the ordering detail is placed where it will be read. It is a verbless fragment, which keeps it slightly under-specified rather than maximally 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 one-parameter read with strong annotations and no output schema, the description is close to adequate, but with no output schema the return shape (messages, direction, timestamps, participants) is undocumented anywhere. 'Full thread, oldest first' is a useful hint but not a complete picture.

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?

There is a single parameter with 100% schema description coverage that already explains owner_id as a UUID from a Spur list/search tool. The description only echoes the 'one owner' scoping and adds no format or sourcing detail beyond the schema, so baseline 3 applies.

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 names the concrete resource (the full SMS thread) and scopes it to a single owner, which implicitly separates it from spur_list_sms_conversations. It doesn't explicitly name the sibling it is not, so it stops short of a 5.

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?

There is no when-to-use statement, no prerequisite (e.g., owner_id must come from a list/search call, which only the schema says), and no named alternative such as spur_list_sms_conversations. The agent must infer the usage split from the phrase 'one owner'.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: steps are returned in execution order, app-built reply/open branches are included, and each send step is linked to its template and step_id.

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 dense sentence that front-loads the returned payload rather than burying it. It is economical, though the nested parenthetical makes it slightly harder to parse at a glance.

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, so the description must carry the return shape, and it does: ordering, branching, per-step template type, and step_id. Only minor gaps remain, such as behavior for an unknown or foreign workflow_id.

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 a single parameter at 100% schema coverage, the schema already documents workflow_id as a UUID sourced from a list/search tool. The description adds no further meaning about the parameter, so the baseline 3 applies.

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 names a specific resource (one outreach workflow) and enumerates what is returned: ordered steps, reply/open branches, the template used per send step, and step_id. It implicitly separates itself from sp​ur_list_workflows by emphasizing a single workflow's step detail, though it never states the retrieval verb explicitly.

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?

There is no explicit when-to-use guidance or named alternative; the reader must infer that this is the detail view following a list/search. The only routing hint, that workflow_id comes from a Spur list/search tool, lives in the schema rather than the description.

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=false, so safety is fully covered. The description adds that results include status and recipient progress, giving a hint of the payload, but says nothing about ordering, total counts, or that offset/limit paging applies — with no output schema, more return-shape detail would have been valuable.

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 tight sentence front-loads the resource with zero filler. It loses a point only because the fragment omits the operative verb, slightly reducing upfront clarity.

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 carries the burden of describing returns and only gestures at it ('status and recipient progress'). For a paginated list tool, the absence of any paging or ordering context leaves the definition minimally viable.

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 limit, offset, and the status enum are fully documented in the schema. The description adds nothing about them, and its use of 'status' as a returned field rather than the filter parameter could momentarily blur the distinction between the output and the status input.

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 names the resource (the user's campaigns) and enumerates the campaign types covered (bulk email, SMS, direct mail, outreach), but it is a bare noun phrase with no verb and no differentiation from siblings like spur_get_campaign_stats. An agent can infer it is a listing operation from the name and title, but the description itself never says 'list' or 'returns a list'.

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?

There is no guidance on when to use this versus spur_get_campaign_stats, spur_list_sms_conversations, or other list endpoints, and no mention of the default page size or that results are paged. Usage is only implied by the tool name.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond the annotations: the ordering guarantee (newest first) and that URLs are public and directly embeddable, which is exactly what an agent needs to know before using the result.

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-loaded with what the tool returns, then how to use the output, then how to add images. No filler, and each sentence carries distinct information an agent would otherwise have to guess.

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 compensates by describing the returned fields (public URLs) and their order, and by telling the agent how to consume them in HTML. The only residual gap is pagination/limit behavior for a large image library, which is minor for a simple read tool.

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% for the single 'limit' parameter, so the schema already documents its meaning, default and bounds. The description adds the ordering context implied by 'newest first' but says nothing about what happens when the limit is reached or whether results are paginated, so it stays at the baseline.

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 the specific resource (the user's saved images), examples of what's in it (logos, headshots, property photos), and the return contract (public URLs, newest first). It also names the two sibling tools that add images, so an agent can distinguish listing from creation without reading a schema.

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?

Gives concrete usage context ('Use it as <img src=…> or CSS background-image in postcard, letter or email HTML') and explicitly routes addition to spur_upload_image (device) or spur_save_image (URL). It does not mention when listing is unnecessary or how deletion relates, but the routing guidance for the most likely confusion is explicit.

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 readOnly, idempotent, non-destructive, so safety is covered. The description adds useful scope context (three template sources, two letter-type categories), but says nothing about return format, ordering, or volume. It also references a 'start_from_blank' token that is not a parameter here, which slightly muddies rather than clarifies 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?

Two sentences, purpose front-loaded, no filler. The first sentence is grammatically awkward (colon-delimited list fragment) but still parsable and compact.

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 does describe what comes back (templates annotated with letter type and their source group), which is the key missing piece for an agent. It omits any mention of the category filter or result size/ordering, so it is good 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 coverage is 100%, so the schema already documents category, letter_type, and include_gallery. The description restates the letter-type values in human form (Top First Page / Insert Blank Page) and alludes to the gallery toggle, but adds no filtering syntax, precedence, or default behavior beyond the schema. Baseline 3 is appropriate.

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?

It clearly states this returns letter templates for the user and names the three sources (own/editable, Spur defaults, built-in gallery) plus the letter-type dimension, which distinguishes it from siblings like spur_get_letter_template (single item) and spur_list_message_templates (different resource). The lead is a noun phrase rather than a verb, but the resource and scope are unambiguous.

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 gives concrete next-step guidance: copy a listed template via spur_create_letter_template with base_template_id to redesign, or start from blank. That tells the agent how this list feeds a follow-up action. It stops short of explicitly excluding alternatives (e.g., when to use get vs list), so it is clear context without full 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds no behavioral detail whatsoever — no ordering, pagination, or scope caveats — so it contributes nothing beyond the structured metadata.

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 short sentences with no waste, and the resource scope is front-loaded. It is efficient, though the terseness reflects under-specification rather than tightness of detail.

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 simple, zero-required-parameter read-only list tool with full schema coverage and clear annotations, this is minimally adequate. With no output schema, the description could still say roughly what comes back or whether results are filtered/paged, and omitting that leaves a gap.

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% and the single 'channel' enum is documented as 'Only email or only SMS templates; omit for both'. The description mentions both channels but adds no syntax or default behavior beyond the schema, so baseline 3 applies.

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 is a noun phrase ('The user's saved email and SMS templates') that implies retrieval without stating a verb like list or fetch. It does scope the resource to the user's own templates, which helps separate it from get_message_template and preview_message_template, but the action remains implicit.

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 notes that these are 'what outreach workflow send_email / send_sms steps use', which is background context rather than guidance on when to call this tool. No alternatives are named and no exclusion or prerequisite is given; an agent must infer when to pick this over sibling list/preview 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds useful context beyond that: which ownership classes of templates appear in the result and the fact that only the user's own are editable. It does not mention result ordering or result volume, which is a minor gap.

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 tight sentences: what is returned first, then what to do with the results. No filler or restated name/title, and the actionable routing is front-loaded in the second sentence.

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 no-required-param, three-optional-filter list tool with full schema coverage and annotations, the description covers scope and follow-up actions adequately. It leaves return shape (fields per template, ordering, pagination) unstated, though no output schema exists to compensate.

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 per-parameter descriptions and a size enum, so the schema carries the parameter burden. The description only alludes to the gallery parameter through the phrase 'Spur's built-in gallery' and adds no filter semantics beyond that, so the baseline 3 applies.

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 the specific resource (postcard templates) and enumerates the three scopes returned: user's own editable templates, Spur defaults, and the built-in gallery. An agent can distinguish this from spur_list_letter_templates or spur_list_images purely from the text.

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 routes next steps: copy a default/gallery design via spur_create_postcard_template with base_template_id, or start blank with start_from_blank. It does not say when to avoid this tool (e.g., when fetching a single template by id, which is spur_get_postcard_template), so it stops short of full when/when-not 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 cover safety traits (read-only, idempotent, non-destructive, closed-world). The description adds useful behavioral context by saying it returns all of the user's property lists with ids and sizes, though it does not discuss ordering 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?

Two short sentences with no wasted text. The return content is front-loaded, followed by practical downstream usage guidance.

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 zero-parameter list tool with rich annotations and no output schema, the description provides enough context: it says what is returned (all property lists with ids and sizes) and how the id is used with related tools.

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 there are no parameter semantics to explain. Per the baseline for parameterless tools, a 4 is appropriate.

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 resource as the user's property lists and states the returned fields (ids and sizes). It lacks an explicit verb and does not directly contrast with sibling list tools, but the resource is specific enough to distinguish it from saved-properties and create-list tools.

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 gives downstream usage guidance by naming spur_list_saved_properties, spur_add_properties_to_list, and outreach tools as consumers of the returned id. However, it does not explicitly state when to call this tool versus alternatives such as spur_list_saved_properties or spur_create_property_list.

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=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the returned field set and the cross-entity relationship (postcard templates), which is useful, but says nothing about ordering, pagination, or behavior for a user with no QR codes.

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 compact sentences: the first front-loads what is returned, the second gives the follow-up actions. Every clause carries information and nothing is redundant.

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 responsibly enumerates the salient return fields and neighbor tools, which is enough for a zero-param read. Only minor gaps remain (result ordering, empty-list behavior), which are low-risk for this tool.

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 takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to compensate for, and it does not waste space restating schema content.

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 the resource (the user's tracked QR codes) and enumerates what each record contains: destination URL, colors, and which postcard templates print it. The listing verb comes from the name/title rather than the description, but the scope is unambiguous and clearly distinct from spur_get_qr_code_activity (scans) and spur_create_qr_code.

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 routes the agent to two explicit alternatives with their conditions: use spur_add_postcard_qr_code to attach a code to a postcard, and spur_get_qr_code_activity for scan data. It does not spell out an explicit 'use this when you need an inventory of codes' statement, but the implied context is strong.

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 readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful data context, namely that one address is flagged as the default and that default is applied implicitly by campaigns, but says nothing about ordering, count, or what fields are returned.

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 tight sentences with the resource definition front-loaded and the default-address note following. Every sentence carries new information; nothing is repeated from the name or annotations.

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 zero-param read with annotations already covering the safety profile, the description is nearly sufficient, and the default-address note hints at a meaningful field in the response. The only gap is that with no output schema, it doesn't characterize the returned record fields, but this is minor for such a simple tool.

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 takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. Nothing in the description misrepresents the input surface.

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 identifies a specific resource (return addresses saved for direct mail) and implies a listing operation, matching the 'list' verb in the name and title. It is clearly distinct from template/campaign/QR siblings, but the verb itself is only implied rather than stated.

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?

Usage is implied: an agent would call this to inspect stored return addresses before a direct-mail campaign. It adds one contextual note (the default address applies when a campaign doesn't specify one) but gives no explicit when-to-use routing or prerequisites, though there is no obvious sibling alternative for this resource.

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 annotations already declare this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context about the response shape ('Shows cards and a map'), but says nothing about pagination behavior, result ordering, or what happens when filters match nothing.

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 sentences with no wasted words, and the core action plus optional filters are front-loaded ahead of the output note. Appropriate for an eight-parameter read 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?

With no output schema, the description does note the response presentation (cards and map), and the annotations cover safety and idempotency. The main remaining gap is the absence of any implicit result-size or pagination expectation, though limit/offset are documented in the 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 description coverage is 100%, with examples for city/state, defaults and bounds for limit/offset, and unit notes for price, so the schema carries the parameter burden. The description only lists four of the eight filters and adds no syntax or format guidance beyond the schema, making the baseline 3 apt.

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 ('List properties the user has saved') and enumerates the filter dimensions, which lets an agent distinguish it from the mutating siblings like spur_save_properties. It stops short of naming the closest alternative, spur_search_properties, so the differentiation from search is only implied by the word 'saved'.

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 phrase 'properties the user has saved' implies a usage context, but there is no explicit statement of when to use this over spur_search_properties or spur_get_property. No prerequisites or exclusions are given, so the agent must infer the boundary between listing saved records and searching.

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 annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds that results include schedule, filters, and run timestamps, but it does not describe ordering, pagination, or whether all automations are returned.

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 compact phrase with no redundancy. It front-loads the core resource and then lists the relevant returned fields.

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 zero-parameter, read-only list with comprehensive annotations, the description covers the key returned data. It leaves minor gaps around result ordering and pagination, but the tool is simple enough that these are not critical for 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?

There are no input parameters, so there are no parameter semantics to explain. The baseline of 4 applies because the schema requires no additional description.

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 identifies the resource as scheduled property searches and enumerates the returned details (schedule, filters, next/last run times), so an agent can distinguish this listing from creation or execution siblings. It does not open with an explicit list verb, but the title and content make the operation clear.

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?

There is no explicit guidance on when to use this tool versus alternatives such as spur_create_search_automation or spur_run_search_automation. The usage is only implied by the phrase 'Scheduled property searches with...'.

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond that: ordering (newest first) and the returned fields (unread counts, last message), which the agent needs for triage. It doesn't mention pagination or limits on totals, keeping it from a 5.

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 tight sentences, zero waste, with the core purpose and ordering front-loaded before the use case.

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 carries return-value burden and does describe the key shapes (unread counts, last message, ordering). Reasonably complete for a simple no-arg list tool, though it omits any detail on conversation fields or result limits.

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 both parameters are fully documented. The description alludes to unread state but adds no syntax or format detail beyond the schema; baseline 3 applies.

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 a specific verb and resource (SMS conversations) plus scope (with owners), ordering (newest first), and return payload (unread counts, last message). It is clearly the list analog to spur_get_sms_conversation, though it never explicitly names that sibling.

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?

Gives concrete triage use cases (hot leads, not interested, wrong number) which tell the agent when this tool fits. It stops short of explicit when-not guidance or naming alternatives like spur_get_sms_conversation or spur_send_sms.

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 the tool as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value by disclosing that results include status and enrollment counts, which is useful return-shape information not encoded in the annotations or an output schema.

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 with no wasted words. It immediately specifies the resource and the key attributes returned.

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 zero-parameter, read-only list tool with annotations covering safety and no output schema, the description provides enough context about what is returned (workflows with status and enrollment counts). It could be slightly more complete by noting whether all workflows are returned or how it relates to spur_get_workflow, but it is largely sufficient.

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 there are no parameter semantics to describe. The baseline for a parameterless tool is 4, and the description does not introduce confusion about inputs.

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 identifies the specific resource (multi-step outreach workflows, email/SMS/mail sequences) and the fields included (status, enrollment counts), which is clearer than the title alone. However, it does not explicitly distinguish this list operation from the sibling spur_get_workflow tool, leaving some ambiguity about when to use which.

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?

There is no explicit when-to-use guidance or mention of alternatives such as spur_get_workflow. The description only states what the tool returns, not the context in which an agent should select it over other workflow-related 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description adds useful context that the interaction happens in an external Stripe portal and that the user (not the agent) performs card updates and cancellations. It does not say whether calling it creates a session, whether the link expires, or that no billing change actually occurs server-side, which matters because 'cancel the subscription' could be misread as an action the tool performs.

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 front-loaded sentence: the core resource comes first, then the concrete capabilities. Nothing is padded or repeated from the title.

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 parameters and no output schema, the description should at least imply the return value and link lifecycle; 'Link to the user's Stripe billing portal' hints at a URL but never states it is a returned link, nor anything about expiry or single-use behavior. It is adequate to call the tool, but leaves the agent guessing about the result.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. No misleading parameter-like language is introduced.

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 names a concrete resource (the user's Stripe billing portal) and enumerates what that portal enables (update card, download invoices, change/cancel subscription), which is far more specific than the tool name 'spur_manage_billing' alone. It does not, however, distinguish itself from the close sibling spur_show_billing_options, leaving the boundary between the two unclear.

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?

There is no statement of when to use this tool versus spur_show_billing_options, spur_get_billing_summary, or spur_change_plan, all of which sit in the same billing cluster. The presence of a near-identical sibling makes the missing routing guidance a real cost, not a formality.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: it consumes no search credit and performs no search. The note that exclusions are honored by omitting filters is useful semantic disclosure. It stops short of describing the exact shape of the returned argument set, which is the only remaining gap.

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?

Front-loaded with the core promise, then cost/credit rationale, then chaining guidance, then exclusion semantics. Every sentence carries distinct information with no repetition of schema or annotations.

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, and the description compensates by explaining what the return is (arguments passable directly to spur_search_properties) plus the caveats on carrying location/status forward. An agent has everything needed to call it and use the result.

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 one parameter at 100% schema coverage, the baseline is 3; the description earns a step up by clarifying that the query is plain-English and that filters, events, and exclusions are all parsed out of it — meaning the agent knows free-form phrasing is acceptable.

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 a specific verb and resource — show how Spur interprets a plain-English property search into filters and events — with the crucial qualifier 'without running it.' This clearly distinguishes it from sibling spur_search_properties, which actually executes the search.

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?

Gives explicit when-to-use ('confirm intent before spending a credit', 'turn a vague request into explicit filters') and names the downstream alternative, spur_search_properties, with a constraint on reusing location/status. Exclusions handling is also spelled out.

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 readOnlyHint=true already declared, the description adds substantial context the annotations cannot: the token's 30-minute expiry, its exact scoping (this template, letter type, print options, recipient set, return address), what gets computed (address check, cost estimate, blank-page surcharge), and that no mail is sent here. Nothing contradicts the readOnly/idempotent hints.

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 tight paragraphs: the mandatory-step requirement and token semantics lead, the approval workflow follows. Every sentence carries actionable information with no repetition of schema fields.

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 preview tool with no output schema, the description still tells the agent what comes back (rendered letter on real data, address availability, cost estimate, confirmation_token) and the full lifecycle constraint on the token. Nothing needed to invoke or follow up correctly is missing.

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 the baseline is 3; the description goes beyond it by explaining that print options and the return address are part of the binding token scope, and by noting the Insert Blank Page address page affects the cost estimate. It stops short of mapping each individual parameter, which the schema already handles well.

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 names a specific verb (renders/checks/estimates/returns token) and resource (letter campaign preview), and clearly separates it from the sibling preview tool (spur_preview_letter_template) and the downstream action (spur_send_letters). An agent can identify this as the mandatory pre-send rendering step without opening any schema.

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 states an explicit precondition ('Required step before mailing letters') and an explicit sequence: show the preview, get user approval, then call spur_send_letters with the token, noting the widget Send button is equivalent. Both when-to-use and the alternative path are spelled out.

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 readOnly, idempotent, and non-destructive, so the safety bar is low; the description adds the substantive behavior that output is a rendering populated with sample data rather than the stored template itself. It does not describe what the sample data is or whether rendering costs anything, which keeps it short of a 5.

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 that front-loads the scope of valid inputs and ends with the key non-mutation guarantee. 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 present, the description does well to state that a rendering is produced with sample data. It stops short of clarifying the return form (image, HTML, link) or how sample data is chosen, a minor gap for a preview tool.

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 the parameter already documents that the id comes from spur_list_letter_templates and may be a UUID or gallery id. The description's parenthetical about template sources restates that rather than extending it, so baseline 3 applies.

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?

Specific verb 'Show' plus resource 'letter template', with scope enumerated (yours, Spur default, gallery design) and outcome stated (rendered with sample data). An agent can distinguish it from spur_preview_message_template and spur_preview_postcard_template purely from the resource named.

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?

'Without changing anything' clearly signals a safe preview/inspection context, implying use before committing to sending. It does not, however, name an alternative such as spur_get_letter_template for fetching raw template data, so the when-to-use-vs-sibling boundary is only inferred.

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=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: nothing is saved, design checks run, sample versus real owner data can be used, SMS segments are billed, and links from unverified numbers may be blocked. It does not describe the preview or design-check output, so 4 rather than 5.

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 opening is front-loaded and the channel-specific paragraphs are clearly separated. However, the description is quite long for a preview tool and includes extensive design-guide material that is also available through spur://email-design-guide, so it is informative but not tightly 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?

Given six parameters, closed-world read-only annotations, and no output schema, the description covers the important channel rules, image handling, merge fields, opt-out requirements, and the save workflow. It still does not describe what the preview or design checks return, and it does not explicitly route saved-template previews to spur_preview_message_template.

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 the baseline is 3 even though parameter details are already structured. The description adds meaningful HTML/SMS content guidance, but it references 'text_body' while the actual parameter is 'text', and says to keep HTML under 50,000 characters while the schema allows 200,000, introducing avoidable confusion.

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 first sentence states the specific verb (Preview), the resource (email HTML or SMS text), and the lifecycle scope (before saving). 'Nothing is saved; iterate here, then save with spur_create_email_template / spur_create_sms_template' clearly separates it from create-template siblings, so an agent can identify its role without opening other schemas.

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 gives a clear usage context: preview and iterate before saving, then use the create-template tools; owner_id selects real owner data instead of sample data. It does not explicitly say when to use this versus sibling preview_message_template for already-saved templates, so it falls short of full when/when-not 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?

Adds real value beyond the readOnlyHint/idempotentHint annotations by disclosing what the preview contains: desktop and mobile inbox renderings for email, phone view plus segment count for SMS, and design checks. The 'changes nothing' statement reinforces the non-mutating trait concisely.

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 dense sentence plus a two-word safety statement. The rendering details are front-loaded and every clause (channels, views, data source, design checks) carries distinct 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?

With no output schema, the description does the work of telling the agent what comes back — rendered views, segment counts, and design checks. Only gap is no indication of output format/structure, but for a preview tool this is close to sufficient.

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 the owner_id description already explains 'real data instead of sample data', so the description's mention of sample vs real data is largely redundant. Baseline 3 is appropriate when the schema fully documents both 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?

Specific verb (preview/show) plus resource (saved email or SMS template) and the rendering modes (inbox view desktop/mobile, phone view, segment count). It distinguishes itself from retrieval siblings like spur_get_message_template by making clear it renders rather than returns raw template data, though no sibling is named explicitly.

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 'sample data or a real owner's data' clause gives clear context for when to use each mode, and 'changes nothing' signals this is a safe inspection step before sending. No explicit exclusions or named alternatives (e.g. preview_message_draft vs get_message_template) are given.

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 the read-only and non-destructive profile, and the description adds critical workflow behavior: token generation, 30-minute expiry, exact scope binding to template/recipient set/return address/size, and the approval gate before sending. These details materially affect correct invocation and are not present in the 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 front-loaded with the core requirement and purpose, then states the approval workflow and token constraints without wasted filler. Every sentence adds operational value.

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 lack of an output schema, the description still explains what the tool returns (a confirmation_token) and what the preview includes. It also covers the required approval workflow and token lifecycle, which are the non-obvious pieces an agent needs to call this 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 parameter documentation is already strong. The description adds useful cross-parameter meaning by explaining that the confirmation_token is scoped to the exact template, recipient set, return address, and size, which helps an agent understand how the parameters constrain the downstream send call.

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: preview a postcard mailing campaign. It also enumerates concrete actions (render with real recipient data, check addresses, estimate cost, return a confirmation_token), clearly distinguishing it from spur_preview_postcard_template and spur_send_postcards.

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 explicitly says this is a required step before mailing, instructs the agent to show the preview and ask for approval, and names the exact follow-up tool spur_send_postcards with the token. It even notes the widget's Send button performs the same approval path.

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 readOnly, idempotent and non-destructive, so 'without changing anything' largely repeats them. The one genuinely additive fact is that output is a render using sample data rather than real recipient data, but return format and what the preview contains are left unstated.

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?

One tight sentence with zero waste, and the resource scope is front-loaded before the sample-data qualifier.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.