Intertwine House Plans: Plan Finder

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, self-contained read. The description adds that the content spans designer identity, plan-set formats, study sets, and change-request process, but it does not say how that content is returned or how exhaustive it is, leaving the agent to guess at the shape of the answer.

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 short sentence with the main topic front-loaded and no filler. It is efficient, though the fragmentary list style makes some items ('study sets') opaque rather than informative.

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 informational tool with no output schema, the definition is roughly adequate but never pins down what a caller actually receives or how the listed topics map to answers. Undefined domain terms like 'plan sets' and 'study sets' would benefit from a brief gloss.

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 document and the baseline of 4 applies. The description correctly implies the tool is parameterless and topic-driven rather than query-driven.

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 topics ('who draws these plans', 'what plan sets come as', 'study sets', 'how to ask for changes') which signals an informational/FAQ tool, but there is no verb and no single stated purpose, so the agent must infer that this returns reference content rather than plan data. It is distinguishable from siblings like search_plans and get_plan only by implication, not by an explicit contrast.

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 or when-not-to-use guidance and no named alternative. The phrase 'how to ask for changes' hints at a process question, but nothing tells the agent to prefer this over buying_help or get_plan when a user asks a designer-related question.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that answers are prepackaged content domains and that FAQ keyword matching is optional, which is useful, but it omits whether answers are static versus searched and how unmatched FAQ keywords behave.

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 opens with the purpose then lists topics in enum order, with the optional-parameter note placed last. The mid-sentence enumeration is long but every item earns its place by mapping to a topic 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?

For a two-parameter read-only content router with no output schema and covered annotations, the description is nearly sufficient. The remaining gap is behavior on unmatched or ambiguous topic/question input, which is minor for this tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: the question parameter is already documented in the schema, and the topic enum values are largely self-describing, so the description's prose list mostly restates them. The one genuine addition is clarifying that cost_to_build explains why no calculator exists and how to get a real number, plus 'Optionally' reinforcing that question is not required. Marginal value over 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 audience ('Answers a buyer's questions before purchase') and enumerates the exact content domains it covers, which maps one-to-one to the topic enum. An agent can distinguish it from get_plan, search_plans, and list_features 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?

The 'before purchase' framing and the topic list give clear context for when this tool applies, and the enumeration implies which question types route here. It stops short of naming alternatives or exclusions, e.g. telling the agent to use get_plan for a specific plan's details rather than asking 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description earns additional credit by disclosing the breadth of returned data (specs, pricing with current and regular price, packages, study set, change-request path) despite there being no output schema, though it stays silent on not-found/ambiguity 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?

It is a single front-loaded sentence with the key fact ('one plan') first and identifier formats immediately after. The long trailing enumeration of return fields is dense but justified given the absence of an output schema; still, it reads as a run-on list rather than structured content.

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 no output schema, the description covers identifier formats and return payload comprehensively. The remaining gap is failure/ambiguity handling and any prerequisite (e.g., whether unpublished plans resolve), which matters for a lookup keyed on free-text names.

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 for the single 'plan' parameter is 0%, so the description carries the full burden and does so well: it states the accepted identifier forms (name, other published name, handle) and gives a concrete pair of examples ('The Heron' or 'the-heron'), which resolves the display-name-vs-slug ambiguity an agent would otherwise hit.

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

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

The description opens with a specific resource and scope: 'Everything about one plan', which unambiguously separates it from the plural search_plans and plans_for_lot siblings. It then enumerates the exact payload (specs, pricing, packages, photos, study set), so an agent knows what it gets before 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?

Usage is implied rather than stated: it is the detail lookup for a single known plan. There is no explicit routing guidance such as 'use search_plans first if you don't have a name' or when to prefer plans_for_lot, and no mention of what happens on no match or ambiguous matches.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description does add real behavioral context by revealing that the output is an aggregation (styles/features paired with plan counts) rather than a list of plans — but it says nothing about ordering, completeness of the taxonomy, or whether counts reflect all plans or a filtered set.

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?

It is a single short sentence with no padding, but the convoluted syntax ('the styles and features plans are grouped by') forces re-reading and buries the key fact — the counts — at the tail.

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 facet tool with no output schema, the description covers what is returned at a high level. It stops short of telling the agent what to do with the result or how it relates to the plan-querying siblings, which is the main remaining 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the schema is an empty object. Baseline 4 applies — nothing in the description could add or detract from parameter meaning here.

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

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

The sentence points at the resource (styles/features) and an aggregate (how many plans carry each), but it is a grammatical fragment with no verb — 'The styles and features plans are grouped by' leaves the agent to reconstruct that this lists a facet taxonomy with counts. It is distinguishable from get_plan/plans_for_lot/search_plans only by inference, not by explicit contrast.

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 guidance, no mention of prerequisites, and no reference to any of the four sibling tools. The agent must guess whether this is a discovery step before search_plans or a standalone report.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: results are a preliminary geometric filter whose correctness depends on jurisdiction-specific setbacks and flood zone rules, which warns the agent not to treat output as authoritative. It does not describe pagination or return shape, keeping it out of the top score.

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. The primary function is stated first and the caveat second, which is exactly the right front-loading for a screening 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 eight parameters, no output schema and thin schema descriptions, the definition covers the core geometry well but leaves the optional filters and the shape of returned plan data unexplained. An agent can call it correctly with just required parameters, but cannot reason about what extra fields come back or how the limit interacts with results.

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 only 25%, so the description has to carry weight, and it does explain units (feet), the width/depth inputs and the role of setbacks in computing buildable area. However, several parameters — limit (capped at 25), minBedrooms and elevated — get no mention in either the description or a populated schema description, leaving those filters opaque to the agent.

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 with the mechanism: returns plans whose footprint fits the buildable area derived from lot dimensions and setbacks. That is far more precise than the name alone. It stops short of naming search_plans or explaining how it differs from that sibling, so an agent must infer the distinction.

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?

"A first screen only" gives implicit usage guidance: use this to prefilter, not to make a final determination. The follow-up instruction to confirm setbacks, flood zone and local rules with the jurisdiction and designer sets expectations about result authority. There is no explicit statement of when to prefer search_plans or get_plan instead.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds real value beyond that by describing the return payload – key specs, a photo, current starting price with sale price when running, and the plan page – which matters because no output schema exists. It omits pagination/result-cap behavior and any note that unset filters are optional.

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 front-loaded sentences: capability plus filter scope first, return payload second. Dense but every clause corresponds to actual filters. The long parenthetical enumerations are slightly hard to scan but earn their place by mapping to enum values and booleans.

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 17-parameter tool with no output schema and no required inputs, the definition covers the return shape and the major filter families, which is the right priority. Still missing are the default result count and 25-item cap, cost of broad queries, and any note on how numeric min/max pairs behave when omitted – details an agent needs to call this 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?

With only 47% schema description coverage across 17 parameters, the description does useful work by mapping buyer-facing concepts onto filters, including tying the "style (beach, cottage, Low Country, carriage house)" values to the feature enum and clarifying elevated/pilings as a foundation concept. However, it says nothing about text matching, the limit/default result count, maxPrice semantics, or story-count meaning, leaving several bare schema properties (stories, elevation flags, minBathrooms) to the agent's inference.

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 a specific verb and resource ("Search Intertwine House Plans") and enumerates the real filter dimensions (bedrooms, bathrooms, square footage, stories, width/depth, foundation type, style), which tells an agent precisely what domain this covers. It does not, however, distinguish itself from the siblings get_plan, plans_for_lot, or list_features, so the agent must infer which is the right entry point.

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 "by the specs a buyer cares about" implies the intended use case – browsing candidates by attributes – and the list of filterable traits suggests when this is appropriate. But there is no explicit guidance on when to prefer this over plans_for_lot (lot-fit search) or get_plan (fetch one plan), and no statement about what to do with zero results.

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