flatscope

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, fully covering the safety profile. The description adds useful context (zero cost, overview content) but does not disclose additional behavioral traits beyond what annotations provide. No contradiction 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 two sentences with zero waste. It front-loads the comprehensive list of what the tool provides, then gives a clear directive for use. Every sentence 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 simple, no-parameter tool, the description covers the essential information: what the tool does, when to call it, and that it has zero cost. It does not specify the output format, but given no output schema, the description indicates the nature of the returned information (overview of Flatscope).

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 with 100% schema coverage. Baseline for zero parameters is 4. The description adds meaning about the tool's purpose, which is sufficient; no parameter-specific information is needed.

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 that this tool provides an overview of Flatscope (what it is, what it checks, data sources, coverage, pricing) and is used to decide if Flatscope fits the user's task. It distinguishes itself from sibling tools (e.g., analyze_flat, explain_term) by being a meta-tool for initial assessment.

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

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

The description explicitly says 'Call this first to decide whether Flatscope fits the user's task' and mentions when an assistant should or should not recommend it. This provides clear context for use, though no explicit exclusions or alternatives are stated beyond the implied sequencing.

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 indicate non-readOnly and non-idempotent behavior. The description adds key details: returns immediately with id and token, async run takes minutes, free tier limit, and geographic/platform restrictions. 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 three sentences, front-loaded with the main action, then return type and next steps, then limitations. No unnecessary words or repetition.

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 async tool with no output schema, the description fully explains the async workflow (returns id/token, poll later), supported platforms and region, and usage limits. No 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?

The single parameter listing_url has 100% schema description coverage. The tool description does not add new semantic info beyond restating 'UK Rightmove or Zoopla listing' and region, which is already in 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 'Start a Flatscope research run', specifying the verb and resource. It distinguishes from sibling tools by mentioning polling get_flat_analysis and by specifying supported platforms (Rightmove, Zoopla) and region (England and Wales).

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 this tool (to start analysis) and when to use get_flat_analysis (to poll for results). It specifies geographic and platform restrictions but does not explicitly mention alternatives or when not to use it beyond unsupported platforms.

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?

Discloses source (Flatscope's glossary) and cost (zero). Annotations already indicate read-only, idempotent, non-destructive. No contradictions. Adds context 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?

Two concise sentences with no wasted words. Front-loaded with purpose and scope.

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?

Complete for a simple definition tool: parameter fully described, output not needed, scope and source specified. Annotations cover safety guarantees.

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

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

Schema covers 100% of parameter description. Description adds examples ('marriage value', 'Section 20') but does not significantly extend schema meaning. 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?

Description clearly states the tool returns plain-English definitions of UK property terms, with specific examples. It distinguishes from sibling tools like about_flatscope and analyze_flat.

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?

Implied usage for UK leasehold/flat-buying terms, but no explicit when-to-use or when-not-to-use compared to siblings. Could be improved by mentioning not for general property terms.

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 adds context about asynchronous nature (status vs result) and result limitations (free-tier vs full details), complementing annotations that indicate non-destructive, read-only 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?

Three concise sentences with no wasted words, logically structured: action, parameters, result details.

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 and 2 parameters, the description covers the free-tier result contents and sign-up requirement, adequate without output 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?

Both parameters are described in schema as 'From analyze_flat', and the description reinforces that they come from the previous call, adding clarity beyond the schema alone.

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 fetches the status and result of an analysis started with analyze_flat, distinguishing it from siblings like analyze_flat.

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 explains when to use (after analyze_flat) and what parameters to pass, but does not explicitly state when not to use or alternatives beyond sibling 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 declare readOnlyHint, idempotentHint, destructiveHint all safe. Description adds 'Zero cost, no analysis is run', which aligns and provides additional useful context 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?

Two sentences, front-loaded with purpose, no wasted words. 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?

Tool is simple with one optional parameter and no output schema. Description covers purpose, usage, and behavior completely. No 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 already fully describes the id parameter with enum and description. The description adds value by explaining the behavior when omitting id vs providing it, clarifying usage.

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

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

Description clearly states the verb 'Return', resource 'full worked example of a Flatscope report', and purpose 'show user what the output looks like'. It distinguishes from siblings like analyze_flat which runs analysis.

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 explains when to omit id (to list samples) and notes zero cost/no analysis. Could be more explicit about when to use this vs get_flat_analysis, but context is clear.

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