Agentic House Search

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds substantial behavioral context: concurrent fetching, output format, and critical comparability caveats (e.g., deprivation ranks not cross-nation comparable, mobile data at local authority level, crime data gaps). 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?

The description is well-organized with clear sections (Args, Returns, Caveats, Examples, Exclusions) and front-loaded with the core purpose. It is somewhat lengthy, but the length is justified by the tool's important comparability warnings and usage nuances.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all relevant aspects: purpose, usage, parameter behavior, return format, caveats, and alternative tools. Even with an output schema available, it explains the table layout and limitations, making it fully complete for agent decision-making.

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

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

The input schema fully describes each parameter with constraints and enums (100% coverage). The description's Args section largely restates schema information; the only extra advice ('keep it tight') is also present in the schema. Thus the description adds minimal value beyond the schema.

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

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

The description clearly states the tool's function: comparing 2-5 UK postcodes side by side on selected categories. It names the specific verb 'Compare' and resource 'UK postcodes', and differentiates it from siblings by naming alternatives like postcode_report for single postcodes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Don't use when' section provides clear exclusions with named sibling tools (postcode_report, postcode_search_datasets) and examples of appropriate use cases. This is exactly the guidance an agent needs to select the right 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. The description adds value by disclosing what is returned (home page, endpoint, API docs, format, licence, etc.) and the error behavior (closest matching ids when id not found). 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?

The description is well-structured and front-loaded with purpose. It includes only necessary sections: a concise summary, Args, Examples, and Errors. Every sentence contributes useful information without redundancy.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description is complete. It lists what the returned entry contains, accepts an optional output format, and explains error handling. The presence of an output schema means return value structure need not be detailed further.

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

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

The input schema has descriptions for only 1 of 2 parameters (50% coverage), so the description compensates by providing an Args section with examples for id and the default/options for response_format. This adds practical meaning beyond the schema's enum and type declarations.

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

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

The description clearly states 'Full registry entry for one dataset, by id' with a specific verb ('Get'), resource ('registry dataset'), and scope ('by id'). It distinguishes itself from sibling tools like postcode_search_datasets by focusing on retrieval of a single entry rather than searching or comparing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when you have a specific registry id and need complete details to call the source directly. It also includes examples and error fallback behavior. However, it does not explicitly mention alternatives or when not to use it, though the context 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?

Beyond the read-only/idempotent annotations, the description discloses critical behavioral nuances: deprivation ranks are NOT comparable between UK nations, invalid postcodes return an error with suggestions, and the call is fast with no downstream fetching. This provides rich context without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with distinct sections (summary, usage, args, returns, examples, don't use, note). Although relatively long, every sentence earns its place, and the most important info is front-loaded in the first 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?

With only 2 parameters, an output schema present, and strong annotations, the description still adds essential context: examples, error behavior, cross-nation comparability warning, and a clear pointer to sibling tools. It is complete for an agent to select and invoke 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 the baseline is 3. The description adds value by noting postcode spaces are optional and provides concrete natural-language examples mapping to parameter values, which is beyond the schema's basic 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 uses a specific verb ('Resolve') and resource ('UK postcode to its geography'), enumerating exactly what is returned (coordinates, local authority, ward, constituency, etc.). It also distinguishes itself from siblings by noting it is for checking existence and getting codes, not for area 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?

Explicitly states when to use ('check a postcode exists', 'get codes needed for other datasets', 'when you only need where somewhere is') and when not to ('want data about the area'), naming the alternative tool (postcode_report). This meets the highest bar for 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?

The description goes well beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It discloses that data is assembled live, explains geographic scope caveats (e.g., crime describes a 1 km square, Ofcom coverage describes a local authority), and details normal statuses like 'out_of_coverage', 'unavailable', and 'partial'. It also describes error behavior, making the tool's operational boundaries transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear sections (Args, Returns, Examples, Errors). Every section adds genuine value, from coverage caveats to status explanations, and the opening sentence immediately establishes the core purpose. Despite length, there is no wasted or redundant text.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is remarkably complete for a tool of this complexity. It covers the 11 categories, data sources, geographic benchmarks, normal vs. error statuses, parameter behavior, and provides concrete examples. Combined with the output schema presence, the agent has everything needed to invoke and interpret 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?

The input schema already documents all four parameters with descriptions, including enums and defaults (100% coverage). The main description's Args section mostly repeats the schema rather than adding new semantic meaning. The examples add practical usage context but do not materially deepen parameter understanding beyond what the schema already provides.

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

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

The description clearly states a specific purpose: 'Full neighbourhood report for one UK postcode, assembled live from UK government open data.' It distinguishes itself from siblings like postcode_compare, postcode_lookup, and postcode_get_dataset by emphasizing the comprehensive, single-postcode report nature.

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 clear context for when to use the tool, including natural-language examples and the ability to limit categories. It also states exclusions ('Not a survey, valuation or conveyancing search') and warns users to check decision-critical data against the source. However, it does not explicitly name sibling tools as alternatives, so it stops short of full 5-level 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. The description adds useful behavioral context beyond that: it is a curated registry of exactly 45 datasets, returns paginated results with has_more/next_offset, and supports both markdown and JSON output. 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?

The description is somewhat long but well-organized with Args, Returns, and Examples sections. It front-loads the purpose and every section earns its place, though a bit of redundancy exists between the schema and the Args list. Overall, it is efficient for the tool's complexity.

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 search tool with 5 optional parameters and an output schema, this description is complete. It explains what the tool searches, how to use it, what it returns, and the follow-up tool for deeper detail. The presence of an output schema reduces the need to explain return shape, but the description covers it anyway.

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 high (80%), and each parameter already has a description. The tool description reinforces this by explaining query matches 'name, publisher, category, endpoint and questions', giving concrete category examples, and providing example queries (e.g., 'query="EPC"'). This adds practical value 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 uses a specific verb ('Search') with a clear resource ('curated registry of 45 UK open datasets and APIs') and scope ('for property and neighbourhood research'). It distinguishes from sibling tools by explicitly positioning this as a search/discovery tool, while noting 'Follow up with postcode_get_dataset for the full entry'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage context: 'Use it to find the right source for something this server does not report directly' and lists concrete use cases (EPC ratings, flood risk, etc.). It also names the alternative tool for follow-up, making the division of responsibility between siblings clear.

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