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?

Adds significant behavioral context beyond annotations: asynchronous process returning id/token, takes minutes, limited to Rightmove England/Wales, and free tier. 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?

Three concise sentences with no waste. Front-loaded with action and immediate return, then polling instructions, then constraints.

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 single parameter, good annotations, no output schema, and sibling context, the description covers the necessary async pattern, limitations, and free tier. Could mention what the analysis contains but incomplete without get_flat_analysis sibling.

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 already details the parameter. The tool description repeats the limitation but adds no new semantics beyond what the schema 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 it starts a Flatscope research run on a UK Rightmove listing, using a specific verb and resource. It distinguishes from siblings like about_flatscope (about the service) and get_flat_analysis (polling results).

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 (Rightmove listings in England and Wales) and what not to use (Zoopla/OnTheMarket). Also explains the asynchronous pattern and directs to poll get_flat_analysis, providing clear 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds 'Zero cost' and source (Flatscope's glossary), which are useful but not critical. It doesn't mention error handling if the term is not found.

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 purpose and immediately provides examples, making it efficient for an AI agent to parse.

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 definition tool with one parameter and no output schema, the description covers purpose, examples, source, and cost. A minor gap is the lack of behavior when the term is not found, but this does not significantly harm completeness.

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% with a single parameter 'term' already described as 'The term to define, e.g. 'marriage value' or 'Section 20'.' The description repeats similar examples, adding no new semantic detail 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 'Return' and resource 'UK leasehold or flat-buying term', with concrete examples like 'marriage value'. It clearly distinguishes from sibling tools (about_flatscope, analyze_flat, etc.) which serve different functions.

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 a definition of a UK flat-buying term is needed, and mentions the source and cost. It does not explicitly state when not to use it or provide alternatives, but the context with sibling tools makes the differentiation 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 annotations (readOnlyHint, idempotentHint), describes the asynchronous nature (status vs. ready result) and the content of the return (verdict, score, key facts, viewing questions), adding significant context.

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 redundancy, front-loaded with main action, efficient and to the point.

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 retrieval tool with annotations and no output schema, the description fully explains what is returned and what is not, making the tool's behavior clear and 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 has 100% coverage with terse descriptions ('From analyze_flat.'). The description reinforces that both come from analyze_flat, adding relational context, but does not detail format or constraints beyond what schema implies.

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 or result of an analysis started with analyze_flat, distinguishing it from sibling tools like analyze_flat which initiates the 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 instructs to pass analysis_id and access_token from analyze_flat, and clarifies the free-tier scope and that a sign-up is needed for full data, guiding when to use and alternatives.

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.