MappaIQ

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description usefully adds the geocoding rule ('coordinates are required; an address ... is never geocoded'). Beyond that it says nothing about duplicates, upsert behavior, or the conversation_id handshake workflow, which the schema carries instead.

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 core operation and the key constraint (required coords, no geocoding) front-loaded. Nothing extraneous.

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 18-parameter mutation tool with a nested object and no output schema, the description covers the essential operation but omits the conversation_id sequencing and the bulk-alternative context. Rich schema coverage compensates, keeping this adequate rather than 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 description coverage is 100%, so the schema already documents all 18 parameters, including the geocoding note and customFields. The description's coordinate/address statements largely duplicate schema content rather than adding new 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 and resource ('Add a new record (pin)'), names the container ('to a layer'), and specifies the required coordinate inputs. It is clear enough to distinguish from update_comp, though it does not explicitly contrast with sibling add/bulk_add 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?

No when-to-use guidance is given: it does not say when to prefer this over bulk_add_comps (many pins) or update_comp (existing pins). The address/geocoding note is behavioral, not 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 mark it as a non-read, non-destructive write, so the description carries the real burden and delivers: server-side geocoding, default stage Active, confirmed-today status, caller becomes Listing broker, and the notable fact that an incomplete listing still saves and can surface publicly. It stops short of stating permissions or whether creation is reversible.

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 compact sentences, all front-loaded with the creation action and its key side effects. No wasted clauses, though the final sentence packs several distinct behaviors (partial save, Marketplace visibility, missing-field reporting) into one line.

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 16-parameter non-destructive write with no output schema, the description covers the high-value unknowns: geocoding, defaults, confirmation state, broker assignment, and partial-save behavior. It omits permission requirements and doesn't need to explain return values given no 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?

Schema description coverage is 75%, so most parameters are self-documented and the baseline is 3. The description adds useful semantics for lat/long (falls back to geocoding) and stage default, but does not illuminate the many enum or numeric fields beyond what the schema already states.

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 ('Create one Listing in one call') and the phrase 'one Listing in one call' implicitly distinguishes it from bulk-style siblings in the comp family. An agent can identify this as the single-listing creation tool 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 implied usage context (geocoding is server-side, lat/long optional, starts Active/confirmed) but never names when to use this versus update_listing or close_listing, nor states prerequisites explicitly. The 'ask the Broker for them' hint frames a recovery workflow but not tool selection.

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 and destructiveHint=false, so the write/safe profile is known. The description adds one useful behavioral constraint ("place names are not looked up"), but does not disclose what the call creates/returns or side effects. Adequate but thin on top of 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?

Three tight sentences with no filler, and the core action plus its scoping constraint are front-loaded ahead of the sibling routing. 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 10-parameter write tool the description covers purpose, the area-vs-pin decision, and the coordinate requirement, while annotations and a fully-documented schema carry the rest. The only minor gap is that with no output schema it does not indicate what the tool produces.

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 documents all ten parameters in detail. The description only reinforces the required-coordinates constraint already stated in the latitude/longitude schema entries, adding little beyond what the schema provides. 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?

States a specific verb and resource ("Draw a circular zone ... centered on the given latitude/longitude") and explicitly contrasts itself with the sibling add_comp. An agent can distinguish this from add_comp and add_listing without opening 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?

Names the alternative explicitly and the selecting condition: "Use this instead of add_comp when the user wants an area rather than a single pin." The when-to-use and when-not-to-use cases are both covered.

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 destructiveHint=false, so the safety profile is covered. The description adds the useful detail of what the tool computes (the metric list), which stands in for the absent output schema, but says nothing about cost, limits, or how results 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 zero filler, and the core purpose plus the metric list are front-loaded before the scoping note. 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 read-only analysis tool with annotations covering safety and 100% schema coverage, the definition is nearly sufficient; listing the computed metrics compensates for the missing output schema. It stops short of describing result structure or pagination, which is 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 description coverage is 100%, so every parameter (compIds, layerId, withinGeometry, context, llm_model, conversation_id) is already documented in the schema. The description only alludes to filtered subsets and adds no syntax or format detail beyond what the schema provides; 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 states a specific verb and resource ('Run statistical analysis on a set of comps') and enumerates the computed metrics (averages, median, min/max for price, acreage, $/acre), which clearly separates it from retrieval siblings like search_comps or get_comp_detail. However, it never names an alternative tool or explicitly contrasts itself with them.

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?

'Can analyze all comps or a filtered subset' implies the two operating modes and hints at the compIds/layerId/withinGeometry filters, so usage is inferable. But there is no explicit when-to-use guidance, no statement of when to prefer this over search_comps, and no prerequisites or 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 only declare readOnlyHint=false and destructiveHint=false. The description adds substantial behavior: upsert semantics via externalId, that matching rows are 'updated in place, not duplicated', that missing addresses 'fail with a reason', automatic geocoding, the 1000-row limit, and Marketplace/field behavior under asListings. These are exactly the mutation traits annotations cannot convey.

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 purpose and the add_comp alternative are front-loaded, and each sentence carries operational content. It is a dense single block for a genuinely complex 9-parameter tool, so length is justified, though the long asListings/customFields clauses could be split for readability.

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?

There is no output schema, and the description compensates by describing the return shape (per-row results mapping index/externalId to comp id and status: inserted/updated/failed). Combined with failure modes, limits, and upsert behavior, an agent has everything needed 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?

Schema description coverage is 100%, so baseline is 3, but the description adds real value beyond the schema: it explains the externalId contract (e.g. 'its source Record #') as the idempotency key, the latitude+longitude OR address either/or rule, and the guidance that asListings should only be set on the Broker's instruction. It complements rather than merely repeats 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+resource ('Add many comps') and immediately distinguishes itself from the sibling add_comp by framing itself as the alternative to calling it repeatedly. An agent can tell exactly what this does and when it supersedes add_comp.

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 when-to-use (CSV-style bulk imports, tens to thousands of rows), a named alternative (add_comp), a hard threshold ('split datasets over 1000 rows'), and a clear exclusion on asListings ('never mark rows as listings yourself; set asListings only when the Broker says these are their listings'). This is as complete as usage guidance gets.

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 and destructiveHint=true, so the mutation risk is known. The description adds meaningful non-obvious behavior: existing same-named fields are overwritten while others are added, and it returns a count of updated records. It stops short of stating auth requirements or partial-failure behavior, so not 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?

Four sentences, front-loaded with purpose then mechanics; each sentence carries information. Slightly longer than strictly necessary since the array/targeting sentence partly echoes the schema, but 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 bulk mutation with 100% schema coverage and no output schema, the description covers when to use it, how to target records, overwrite semantics, and the return value. The analytics-only parameters (context, llm_model, conversation_id) are fully documented by 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%, so the schema already documents id, externalId and the {fieldName: value} map. The description restates the id-or-externalId targeting and field map without adding syntax or format 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?

States a specific verb+resource+scope ('Set custom fields on MANY records in one call') and names the single-record sibling it replaces (set_custom_field). An agent can distinguish this from every other sibling without opening 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?

Explicitly says when to use it ('to tag or score an entire dataset after analysis') and names the alternative with the condition that selects it ('instead of calling set_custom_field once per record'). No inference required.

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 readOnlyHint=false, so the agent knows this mutates and can destroy data. The description adds the selection semantics (layer, record-type filter, or both), which is useful, but says nothing about blast radius, reversibility, or what happens to non-matched fields. Adequate against an annotation-backed baseline, but not 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?

Two sentences, no waste, with the core capability front-loaded ahead of the usage examples. 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 six-parameter tool with a nested updates object, no output schema, and 100% schema coverage, the description covers the essential selection model and intent triggers. It omits the conversational bookkeeping (context, llm_model, conversation_id), but those are fully specified in the schema, so the gap is minor.

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 all six parameters, including the updates object, layerName, filterType, and the analytics-only fields. The description only gestures at layerName and filterType, adding 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 ('Update multiple comps at once') with the bulk scope made explicit, and lists the two selection mechanisms. It does not name the single-record sibling update_comp, so an agent must infer the batch-vs-single distinction, but the plural scope is unmistakable.

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 concrete trigger phrasing ('change all pins in layer X to prospecting', 'mark everything in Prospect Sites as a prospecting waypoint') that maps user intent directly to this tool. It gives no explicit when-not guidance or named alternative (e.g. use update_comp for one record), so it stops short of full 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 already declare destructiveHint=true, so irreversibility is partly covered; the description reinforces 'This cannot be undone' and adds genuinely new behavior: the pin becomes a comp and stays public on a public map with the closing price. It stops short of describing the return payload or permission requirements beyond brokerApproved.

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 with the core action front-loaded, followed by the irreversible side effect and the approval gate. Every sentence carries information, though the phrasing of the final clause is slightly awkward.

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 explains the state change and the approval precondition well. The analytics parameters (context, llm_model, conversation_id) are fully documented in the schema, so nothing critical 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 baseline is 3, but the description adds real semantics for brokerApproved by explaining the consequence of omitting it (returns a question rather than closing). It does not clarify date/price defaults beyond what the schema already states.

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 (record that a Listing sold/leased) and names the concrete outcome (pin becomes a comp with closing price and date). This clearly distinguishes it from siblings like add_comp, update_comp, and update_listing.

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 gating condition: 'Without brokerApproved:true it only returns the question to ask the Broker,' which tells the agent when the call will actually close versus when it will bounce back. It does not explicitly contrast against alternatives such as update_listing or add_comp, but the primary usage condition 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?

With destructiveHint=true already declared, the description usefully adds that withdrawn listings are skipped (partial-success behavior) and the timestamp semantics. It does not explain why the operation is destructive or what side effects/irreversibility the agent should expect, leaving a gap against the annotation's severity.

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 sentences with the core action front-loaded and supporting caveats after. Nothing is wasted, though the 'Ask the Broker' sentence reads as policy rather than invocation 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 destructive-flagged single-action tool with no output schema and fully documented params, the description covers effect and skip behavior but omits return/confirmation feedback and the reason for the destructive flag. Adequate but with clear 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 description coverage is 100%, so the schema fully documents ids, context, llm_model, and conversation_id. The description adds no parameter syntax or format beyond the schema; the only related hint ('more than one') loosely maps to the ids array cap.

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 (Mark), resource (Listings), and observable effect (Confirmed date = today), so an agent knows exactly what state change occurs. It is broadly distinguishable from siblings like close_listing or update_listing, but does not name any alternative to sharpen 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?

Provides a real usage constraint – 'Ask the Broker before you confirm more than one' – and notes that withdrawn listings are skipped, which implies partial-success scoping. However, it gives no guidance on when to prefer this over sibling tools like update_listing.

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 safety profile (readOnlyHint=false, destructiveHint=false), and the description correctly presents a creation, not a destructive, operation. It adds genuine behavioral context beyond annotations: the created layer is empty, and mapName matters specifically when multiple maps are in play. It stops short of covering failure/auth/duplicate-name behavior, but the annotation coverage lowers the burden.

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 sentences, each earning its place: the operation, the usage trigger, and the multi-map routing with the alternative tool. The primary purpose is front-loaded before any conditional 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 create tool with annotations covering the safety profile, 100% schema coverage, and no output schema, the description supplies everything an agent needs: purpose, trigger, sibling routing, and multi-map handling. Nothing required to invoke 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%, so the schema already documents every parameter and the baseline is 3. The description adds only a marginal workflow hint for mapName ('list_maps / get_layers tell you which maps exist') that largely restates the schema's own mapName 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?

States a specific verb and resource ('Create a new empty layer inside a map') and immediately differentiates from the closest sibling by naming create_map for the whole-map case. An agent can distinguish this from create_map, move_layer, and rename_layer 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 an explicit trigger ('when the user asks to add or create a new layer'), names the alternative (use create_map first), and points to list_maps/get_layers as the way to resolve which map exists. Both the when-to-use and the when-to-use-something-else conditions are stated.

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=false and destructiveHint=false, so safety is covered; the description adds that the result is empty and what the creation kicks off downstream. It also discloses return values ('the new map's id and name') absent an output schema. It does not say what happens on duplicate names or where the map lands (root vs. folder), so not a full 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 tight sentences, front-loaded with the definition before the when-to-use clause, then the workflow. Nothing is repetitive and every sentence 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?

For a create tool with full schema coverage, the definition covers purpose, triggering condition, downstream sequence, and return values. The only uncovered corner is placement/duplication semantics relative to map folders, which is a minor omission rather than a blocking 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%, so 'name' and the analytics-only 'context'/'llm_model' params are already fully documented; baseline 3 applies. The description's one extra hint — that create_layer takes this map's name as mapName — concerns a sibling's parameter rather than explaining this tool's own 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?

States a specific verb and resource ('Create a brand-new, empty map') and immediately defines what a map is ('the top-level container that holds layers and pins'), which separates it from create_layer and create_map_folder. An agent can distinguish it from every sibling without opening 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?

Explicitly states when to use it versus the nearest alternative: 'Use when the user wants a NEW map rather than a new layer inside an existing one', reinforced with two concrete user utterances. It also sequences the follow-on tools (create_layer with this map's name as mapName, then add_comp/bulk_add_comps).

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 write op (readOnlyHint=false) that is not destructive. The description adds two useful behavioral facts: omitting parentFolderName creates at the Library root, and parent matching is case-insensitive. It says nothing about duplicate-name handling, failure when the parent does not exist, or idempotency, so it stays at a moderate level.

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 zero filler, front-loading the core action before the disambiguation and the optional nesting parameter. The inline examples clarify intent without padding.

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 creation tool with full schema coverage and no output schema, the description covers purpose, the optional nesting behavior, and the primary disambiguation. It is slightly thin on failure/edge behavior if the named parent folder is absent, but otherwise sufficient to call 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?

Schema description coverage is 100%, so name, context, llm_model, conversation_id and parentFolderName are all already documented in the schema. The description only re-states the parentFolderName behavior (existing folder, case-insensitive, omit for root) rather than adding format or constraint detail beyond it; 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?

States a specific verb+resource ('Create a Library folder to organize MAPS') and even gives natural-language examples of the user request it fulfills. It explicitly separates itself from the layer-nesting capability an agent might otherwise confuse it with.

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 clear when-to-use (organizing maps into folders) and an explicit when-not with a named alternative ('use move_layer for that'), which covers the main confusion vector. It does not point at related folder tools such as list_map_folders for verifying an existing parent or move_map_to_folder, so routing is good 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 destructiveHint=true, but the description adds substantial context beyond them: deletion is immediate and irreversible, requires user confirmation first, layer deletion removes the layer AND its pins, layer deletion is owner-only, and effects are scoped to the caller's own data plus admin-shared layers. These are real behavioral constraints not derivable from 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?

Front-loads the action and the immediate/irreversible warning, then walks through the modes in order. It runs a bit long, but for a multi-mode destructive tool every sentence (warning, confirmation, three modes, ownership scope) carries functional weight rather than padding.

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, no-output-schema tool, the description covers what an agent needs: the safety profile, the confirmation requirement, permission boundaries, and how to address each target. Nothing required to call 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 100%, so the schema already documents each parameter; baseline would be 3. The description adds genuine value by explaining the combination logic across parameters (scope + layerName without compIds clears pins but keeps the layer; layerId vs layerName resolution), which the individual field descriptions cover only in isolation.

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 resource (pins/records), then enumerates the three deletion modes precisely. No sibling tool in the list performs deletion, and this description makes the destructive scope unmistakable. An agent can tell exactly what it does 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 maps each mode to triggering parameters ('Use compIds to delete specific pins', 'Use scope layer with layerName...', 'Use scope comps with a layerName and no compIds...'). It also states the intent condition ('when a user wants to clear out old/junk pins or empty a layer') and adds a confirmation prerequisite.

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 (readOnlyHint=false, destructiveHint=false) by disclosing exactly what happens: the broker is emailed the user's message and contact info attributed to MappaIQ, it consumes 1 Marketplace credit, and if the broker has no email on file nothing is sent and a phone number is returned instead. That quota and fallback behavior is precisely the kind of 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-loads the core action and the usage trigger, then layers the behavioral caveats (attribution, confirmation requirement, credit cost, fallback) in descending priority. Every sentence carries distinct information with 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?

A mutating, credit-consuming tool with 100% schema coverage and no output schema. The description supplies the side effects, the confirmation requirement, the quota impact, and the alternate return path, leaving no functional gap an agent would need to call it 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 description coverage is 100%, so all six parameters (including the verbose context, llm_model, and conversation_id guidance) are already documented in the input schema. The description adds only marginal parameter meaning by naming search_public_listings as the source of the id, which the schema also states. 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?

States a specific verb and resource: 'Send a lead to a Marketplace listing's broker.' It also anchors the resource to its source ('from search_public_listings'), so an agent can distinguish this contact/broker action from the many listing and comp tools that share the namespace.

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 triggering condition — 'use it when the user wants to inquire about or be contacted about a public listing' — plus a hard procedural prerequisite: 'Always confirm the message with the user before sending.' No alternative tool performs this action, so the absence of an alternatives clause is not a 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context: the filter governs which pins are visible on the map rather than mutating underlying data, and clear:true restores full visibility. It stops short of stating persistence (per-session vs saved) or interaction with other active filters.

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 slider analogy are front-loaded, and the example list is functional rather than filler. It is slightly longer than strictly necessary, but each sentence maps to a real invocation pattern.

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 filtering tool with no output schema, the description covers intent, the date-range semantics, mode selection, and clearing. The remaining schema parameters (context, llm_model, conversation_id) are analytics plumbing documented in the schema itself and need no description-level explanation.

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 from/to/mode/clear in detail, including the 'before 2018' style mappings. The description reinforces mode's role ('picks WHICH date to filter on') and clear's effect but adds little beyond the schema, 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 (filter) and resource (pins visible on the map) with a precise scope ('by year'). The 'exactly like the map's date slider' framing makes it immediately distinguishable from siblings like find_listings or search_comps.

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 to use it ('whenever the user wants to show or hide pins by date') and backs it with five concrete utterance examples mapping to the from/to/clear parameters. It also names the removal case ('To remove the filter... set clear: true'), leaving nothing 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 readOnlyHint=true so the safety profile is known, but the description adds non-obvious behavior: the three outcome states and their required handling, plus the critical distinction that compMatches are closed sales, not listings. It stops short of stating that results may include multiple candidates via a separate field, but the outcome semantics are genuinely useful context 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?

Every sentence carries a distinct instruction, and routing information is front-loaded before the outcome-handling details. 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?

With no output schema, the description compensates by fully specifying the outcome vocabulary and its required responses, which is exactly the return-value information an agent needs. Combined with the comps-vs-listings warning, 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 query, context, llm_model, and conversation_id are already documented in the schema. The description only restates the 'loose words' nature of query, adding little beyond the schema's own 'address, name, city or asset class' description. 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?

States a specific verb and resource ('Find this account's Listings') and scopes the input domain ('from the Broker's own loose words'), which separates it from search_public_listings and get_public_listing. The example inputs make the intent concrete and unmistakable.

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 usage ('Call this first for any listing change') and prescribes behavior per outcome ('one' = act, 'ambiguous' = ask, never guess, 'none' = no match). It also warns against editing comps as listings and directs to add_listing instead, covering both when-to-use 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?

The description adds behavioral detail beyond annotations by explaining it writes 'flagged: true' and a reason that can be queried later, which is useful. However, with destructiveHint=true set, the 'Use freely' framing downplays that the operation mutates persisted record state (and can be used to clear it via flagged=false), so the risk profile is not addressed.

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, front-loaded with the verb and resource, and each clause adds something (tag examples, write behavior, usage guidance, reason pairing). Slightly repetitive in the middle ('flag every outlier, flag every missing field') but overall efficient.

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 mutation tool with no output schema, the description covers what it writes, why, and when to use it. The main omission is any mention of the destructive/mutating implications flagged by annotations, but the core invocation-relevant context is present.

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 documents every parameter in detail, so the baseline is 3. The description's 'Always pair with a clear reason' reinforces the reason parameter but adds no syntax or format 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?

States a concrete verb (tag/flag) plus the resource (a record) and enumerates the kinds of tags it applies, so the agent immediately knows this annotates records with a flagged status. It is distinguishable from set_custom_field and set_callout by being specifically a flag-with-reason action.

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?

'Use freely when doing analysis: flag every outlier, flag every missing field, flag anything the user should review' gives an explicit, actionable usage context. It does not, however, name the sibling alternatives (e.g. set_custom_field/set_callout) or state when NOT to flag, 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — a 100-record cap, that the PDF surfaces as a download button in chat, and that the commentary lands in a client-facing document (implying a quality bar). It does not cover permissions or failure modes, so it stops 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?

Front-loads what the tool produces before the usage trigger and the parameter guidance, so an agent can decide early. It is somewhat dense with multiple clauses, but nearly every sentence carries actionable information rather than 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 7 params, no output schema, and a mutation-adjacent generation task, the description supplies the missing pieces: the output form (chat download button), the input limit, and the sequencing dependency. The remaining params (title, context, llm_model, conversation_id) are well covered by the schema itself, so nothing critical is absent.

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 adds meaning the schema does not: the compIds-vs-layerId preference, the 100-record limit, and concrete content guidance for commentary (2-3 sentences covering pricing range, $/acre, trends, zoning/asset-type).

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 (create) and a concrete artifact (BOV comparable-sales PDF) and enumerates its contents: comp table, price and $/acre ranges, analyst commentary. This distinguishes it from siblings like analyze_comps (analysis only) and generate_file (generic file output).

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 trigger ('user asks for a BOV, comp exhibit, or comp-set PDF') and an ordered prerequisite workflow: pick the comp set via search_comps / analyze_comps first, then write commentary. It also names the parameter alternative and its preference ('compIds (preferred) or a layerId').

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=false and destructiveHint=false, giving the safety profile. The description adds genuinely useful behavior beyond that: the file renders as a download button in chat and tabular excel gets a bold header row. It does not, however, cover what happens on failure or anything about the analytics-only params.

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 when-to-use are front-loaded, followed by format guidance; each sentence carries specific information. It is on the longer side but avoids filler, so only marginally less tight than ideal.

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 9 params at full schema coverage and no output schema, the description supplies the routing logic, format defaults, and return behavior an agent needs. It never explains the required analytics params (context, llm_model), but the schema covers those in detail.

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 each parameter (including the excel-default note on `type`). The description adds cross-parameter guidance (pair type:'excel' with headers+rows; use pdf with a content string), which is a modest value-add but largely overlaps the enum 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?

States a specific verb (create/downloadable file) and resource (file/export) and immediately scopes it to the export/download use case. The reader can distinguish it from siblings like import_file. The format enumeration further pins down the scope.

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 to use it (user asks for export, report, or file download) and provides format-selection rules with a clear exclusion (CSV only if the user explicitly asks; excel is the default for tabular). Routing among formats is unambiguous.

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 destructiveHint=false, so the safety profile is covered elsewhere. The description adds nothing beyond that — no indication of what 'full details' contains, no auth requirements, and no rate-limit or pagination 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?

A single tight sentence with the key noun phrase ('full details for a specific comp by ID') front-loaded and no wasted words. It is terse to the point of under-specification rather than bloated.

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 read-only getter whose annotations carry the safety profile and with no output schema, this is minimally adequate. It still fails to say what fields 'full details' returns, which is the main open question an agent would have.

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; the schema fully documents id, context, llm_model, and conversation_id. The description only echoes the id parameter ('by ID') and adds no meaning beyond the structured fields.

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 ('Get'), resource ('full details'), and scope ('for a specific comp by ID'), which cleanly separates it from search_comps (listing) and update_comp (mutation). It stops short of naming those siblings explicitly, so an agent must infer the boundary from the scope phrase 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?

There is no when-to-use guidance, no mention that an ID must first be obtained (e.g., from search_comps), and no statement of when this is preferable to analyze_comps or the bulk endpoints. Usage is only implied by the 'by ID' phrasing.

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 genuinely useful behavior beyond the schema: no login needed, links open a live interactive map (not a static image), return array shape and input ordering, and that missing IDs are silently omitted. However, annotations declare destructiveHint=true and readOnlyHint=false, and the description never explains what mutating side effect occurs (e.g. that share links are created/persisted) — leaving the destructive hint unexplained.

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-loads the key distinction (one link per comp, not combined) in the first sentence, then layers usage, batching, and return format. Dense and mostly waste-free, though slightly longer than strictly necessary for a getter.

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 compensates by documenting the return array shape ({compId, name, url}), ordering, and omission behavior, plus the bulk-call pattern. The one remaining gap is that the destructive/has-side-effects nature implied by annotations is never explained.

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 compIds, context, llm_model, and conversation_id. The description only reinforces the per-ID granularity and ordering of compIds, adding marginal meaning over the structured fields. 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 (get), resource (share links), and a precise unit of work: one distinct link per comp rather than one combined link. It also explicitly rules out the neighboring concept of layer-wide sharing, so the agent can distinguish it from get_shares 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?

Gives explicit when (individual pin links, bulk requests like 235 comps in one call), when-not (sharing an entire layer — use get_shares or the layer share flow), and how to batch (pass every compId at once instead of repeated calls). Alternative is named and the selecting condition is 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: pin-ID arrays are omitted by default and why (response size on big accounts), and the `map` field only appears on multi-map accounts. It stops short of noting pagination, but that is a minor gap given the read-only annotation.

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 sentences, purpose front-loaded, then the map-disambiguation detail, then the includeCompIds caveat with its alternative. No filler; each sentence carries actionable 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?

With no output schema, the description steps in to describe the return shape (names, comp counts, conditional `map`) and a deliberately omitted field. For a read-only list tool this covers everything an agent needs to call it correctly and interpret 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?

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning: it explains the consequence of includeCompIds (enormous responses) and routes to search_comps, going beyond the schema's terse 'Include each layer's full pin-ID array (large)'. The context/llm_model/conversation_id analytics params are left to the schema, which documents them fully.

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 (get all available layers) and enumerates what comes back (names and comp counts), plus the conditional `map` field. An agent can immediately tell this is a layer-listing tool and distinguish it from pin-finding siblings.

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 tells the agent when to pass includeCompIds:true (only if raw ID lists are truly needed) and names the correct alternative for the adjacent task — 'search_comps is the right tool for finding pins'. Both the trigger and the alternative are stated, not 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=true and destructiveHint=false, so safety is covered. The description adds a genuinely useful behavioral fact beyond the schema/annotations: the call 'Counts as 5 searches against the account's Marketplace limit,' a quota-cost disclosure that steers call frequency. It does not discuss auth or return format, but the safety profile is already annotated.

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 waste: the first front-loads purpose and return contents, the second delivers the quota cost and the usage constraint. 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 read-only detail tool with no output schema and full schema coverage, the description covers what it returns, where the id comes from, and the cost of calling it. Nothing an agent needs to invoke 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%, so all four parameters (including the elaborate context and conversation_id guidance) are fully documented in the schema. The description only reinforces that id comes from search_public_listings, adding marginal meaning. Baseline 3 is appropriate when the schema does 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 (Get), resource (one Marketplace listing by id), and precisely enumerates what it returns: the listing broker's name, brokerage, phone and email. It also names search_public_listings as the sibling that produces the id, so an agent can distinguish this detail-fetch from the search step.

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 routing and condition: the id comes from search_public_listings, and it should be called 'only for listings the user wants to contact about.' That is a clear when-to-use rule tied to a concrete user intent, leaving little 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the constraint that either a person or a layer (or both) must be supplied, but says nothing about result shape, size limits, or how sharing entries are ordered/aggregated.

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 is front-loaded in the first sentence, and the example bullets are concrete and each demonstrate a distinct query shape. The closing 'Always use this tool when...' sentence partly restates the bullet examples, adding mild 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?

For a read-only query with no output schema, the description covers purpose, when-to-use, and the person/layer input contract adequately. It leaves the shape of the returned access data unspecified, which is the one remaining gap an agent might care about.

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 six parameters are already documented, including the conversation_id protocol and includeDescendants default. The description's 'person name/email OR a layer name (or both)' adds a small amount of disambiguation about how personQuery and layerName combine, but nothing beyond what the 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?

States a specific verb and resource ('Query sharing and access information') and the five example questions pin down exactly what the tool returns. The sharing/access framing distinguishes it cleanly from sibling tools like get_layers or find_listings, none of which concern permissions.

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 trigger conditions ('Always use this tool when the user asks about sharing, access, permissions, or what someone can see') and shows representative phrasings. It does not name a when-not case or an alternative tool for adjacent questions, which keeps it just short of a 5.

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 readOnlyHint=false and destructiveHint=false; the description adds real value beyond that with upsert-by-externalId semantics (re-runs update rather than duplicate), the 2000-row ceiling, and geocode-skip behavior for unmatched addresses. However, it says little about permissions/auth requirements or what happens on partial failure partway through a large write.

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 capability and the sibling replacement in the first sentence, with operational caveats following. It is dense and the KML style-junk/MultiGeometry/Lanes-and-ROW details run long for a single paragraph, but every clause conveys actionable behavior rather than 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 12-parameter write tool with no output schema, the description covers parsing, header auto-detection, customField retention, geocoding fallback, upsert keying, batch limits, and the dryRun preview. An agent has enough to call it correctly without opening 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 coverage is 100%, so baseline is 3, but the description adds decision-level meaning: the fileUrl-vs-csvText exclusivity, the dryRun-first workflow, and the strong caution that asListings must come from the Broker rather than column inference. It does not add much beyond the schema for context/llm_model/conversation_id, which the schema already documents thoroughly.

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 opening sentence states a specific verb and resource ('Import an entire spreadsheet of pins in ONE call') and explicitly positions it against siblings ('the direct replacement for looping add_comp/bulk_add_comps row by row'). It also distinguishes the second mode (KML/KMZ/GeoJSON map overlay import) with concrete examples of what those files contain.

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 selection rules: supply either fileUrl or csvText, start with dryRun:true to preview before writing, and set asListings:true only when the Broker says the file is their listings and 'never infer it from the columns'. Alternatives and when-not conditions are both 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 declare a safe read (readOnlyHint=true, destructiveHint=false), so the description only needs additive context. It delivers that by disclosing the result shape (name, id, parent folder, map count) and the nesting behavior of folders, which the annotations cannot convey. Pagination/ordering behavior is the one omission.

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 sentences, zero filler. The scope-and-exclusion statement is front-loaded, the return shape follows, and the workflow hint closes it. 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?

No output schema exists, and the description compensates by enumerating the returned fields and the nesting structure. Combined with a 100%-documented schema and clear read-only annotations, an agent has everything needed 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?

Schema description coverage is 100% and the three parameters (context, llm_model, conversation_id) are fully documented telemetry/session fields, so the description correctly spends no words on them. Per the high-coverage baseline this is a 3 — nothing added, nothing missing.

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 (List) and resource (Library folders organizing MAPS), and explicitly excludes layers, which is the nearest confusing sibling. An agent can distinguish it from list_maps, get_layers, and list_public_maps 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 positions the tool in a workflow: 'Use before create_map_folder or move_map_to_folder to see what exists,' naming two concrete alternatives and the condition that makes this the right call. It does not state when NOT to use it, so it falls just short of full when/when-not coverage.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return shape (name + id) and the map/layer hierarchy, but no pagination, ordering, or scoping details beyond that.

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 purpose, then the usage triggers, then a clarifying definition of 'map'. Three tight sentences, none 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 simple read-only list tool with annotations covering safety and no output schema, the description says enough to call it correctly. Minor gap: it doesn't clarify relationship to list_map_folders or list_public_maps.

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 three parameters are analytics bookkeeping fields (context, llm_model, conversation_id) fully documented in the schema. The description adds nothing about parameter usage, so the 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?

States a specific verb and resource ('List all of the user's maps') and even specifies the returned fields ('name + id'). It also disambiguates the domain model ('A map is the top-level container; layers live inside a map'), which distinguishes it from layer-oriented siblings like get_layers.

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 concrete when-to-use triggers: before creating layers/comps, to verify creation, or when the user asks what maps they have. Clear context, but it never names competing alternatives such as list_public_maps or list_map_folders to route the agent away from them.

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 destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the marketplace scope spans accounts, it enumerates returned fields (name, owner profile URL, pin/layer counts, pageUrl), and notes the optional keyword filter. No auth or rate-limit detail, but the added value is real.

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, followed by scope, return fields, and the routing hint — a sensible order. The 'brokers and owners across the industry publish their listing portfolios here' clause is somewhat promotional filler but the overall density is acceptable.

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 helpfully enumerates the return fields and provides a pageUrl link. Scope and the pin-level alternative are covered. The meta-parameters (context, llm_model, conversation_id) are self-documented in the schema, leaving only minor 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 description coverage is 100%, so the schema fully documents all four parameters including keyword, context, llm_model, and conversation_id. The description's mention of 'optional keyword filters by map or owner name' merely restates 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?

States a specific verb and resource ('Browse the OPEN MARKETPLACE: every map any MappaIQ user has published as Public') and immediately scopes it against the connected account, which distinguishes it from the sibling list_maps. An agent can tell what it returns and how it differs from other 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?

Explicitly routes the pin-level query to the alternative ('Use search_public_listings to query the pins themselves') and implies the connected-account alternative via 'reaches beyond the connected account.' It gives clear context but never names list_maps explicitly or states when this tool should not be used.

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 readOnlyHint=false, so safety is covered. The description adds real behavioral context beyond them: ambiguous names are refused rather than guessed, both layers must be in the same map, and root is the implicit default when no destination is given. It does not disclose what the response looks like or any error/undo behavior, but the annotation bar is already met.

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 sentences with the purpose front-loaded, followed by the id-preference rule and the same-map/batch constraints. No sentence 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 an 8-parameter mutation tool with no output schema, the description covers the operation semantics, constraints, and invocation method well. It leaves out permission requirements and return/error behavior, which are minor given the destructive hint already flags mutation risk.

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 still adds value by explaining the rationale behind the id-over-name preference (name collisions across maps) and the root-level default, which the schema states mechanically but does not justify.

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 (move) and resource (layer) and enumerates both destinations: into another layer as a child, or to the root. This cleanly distinguishes it from siblings like rename_layer and move_map_to_folder without the agent opening 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 clear invocation guidance: prefer exact ids from get_layers, names are refused when ambiguous, both layers must share a map, and one call per layer for batch moves. It does not explicitly name tool alternatives (e.g. rename_layer for renaming), but the when-to-use context is strong and unambiguous.

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 readOnlyHint=false, so the safety profile is covered structurally. The description adds useful routing context (root vs folder) but says nothing about what the move affects, whether the map leaves its prior folder, or failure behavior when the target folder doesn't exist.

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 sentences with no filler: action and scope first, then the example, then the routing helpers and the sibling exclusion. Nothing is redundant or 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 simple mutation with a fully documented schema and annotations covering the safety profile, the description covers action, destination, alternatives, and name resolution. Minor gaps remain around error cases (unknown map or folder) and whether the source folder is affected.

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 five parameters are documented in the schema itself, including the context and conversation_id analytics fields. The description's only added semantics is the omit-folderName-to-reach-root rule, which the schema also states, so the 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?

States a specific verb (move) and resource (MAP) plus the destination scope (Library folder or root), with a concrete example. It explicitly distinguishes itself from the sibling move_layer, so an agent can route 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?

Names the alternative (move_layer) and the exact condition that selects it, and points to list_maps and list_map_folders to resolve names. The 'omit folderName to move to root' note tells the agent how to trigger the non-default case.

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 destructiveHint=false, so safety is covered. The description adds that coordinates are required and addresses won't be geocoded, which is behavioral context beyond annotations. It doesn't mention side effects or return behavior, but for a read-only navigation tool this is adequate.

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 zero waste. The key constraint about coordinates vs addresses is front-loaded and immediately actionable.

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 navigation tool with no output schema and rich schema descriptions, the description covers the critical constraint (no geocoding) and purpose. It could mention zoom behavior or that it's a view-only move, but the essential information for correct invocation is present.

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 baseline is 3. The description reinforces that latitude/longitude are required and not addresses, adding some value, but doesn't explain other parameters like zoom or context 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?

States a specific verb+resource: 'Fly the map to the given latitude/longitude.' Clearly distinguishes from siblings like create_map or search_places by describing a map navigation action. Minor gap: doesn't explicitly contrast with move_map_to_folder or set_callout.

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?

Implies usage when you have coordinates and need to move the map view. The constraint 'Coordinates are required — addresses are not geocoded' is useful but doesn't provide explicit when-to-use/when-not guidance or name alternatives like search_places for address-based navigation.

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 and destructiveHint=true, so the mutation/destructive profile is covered structurally. The description adds no behavioral context beyond that—no permission requirements, no note on what a rename affects—so it neither contradicts nor enriches 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 short sentences with the core action front-loaded and no filler. The trigger-phrase sentence is slightly redundant with the first but still earns its place as routing help.

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 rename operation whose safety profile is carried by annotations and whose parameters are fully documented in the schema, the description is largely sufficient. A brief note on the destructive flag or required permissions would make it 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 description coverage is 100%, so layerId, newName, context, llm_model, and conversation_id are all documented in the schema itself. The description adds no parameter-level meaning beyond that, 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?

States a specific verb (rename) and resource (layer) that clearly separates it from the sibling rename_map and create_layer. It's clear and unambiguous, though it never explicitly names an alternative tool, so it stops short of full sibling differentiation.

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 trigger phrases ('rename layer X to Y', 'call this layer something else') that map directly to user intent, which is genuinely useful for routing. It does not, however, state when NOT to use it or point to the relevant alternatives (e.g. rename_map, move_layer).

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 and destructiveHint=true, so the safety profile is covered structurally and none of the description contradicts it. But the description adds nothing behavioral beyond that: it does not say whether the rename is reversible, what happens if the new name collides with an existing map, or whether the old name is freed.

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, front-loaded sentences with no filler; the action and its two inputs come first. The list_maps hint earns its place as a practical next step.

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?

Covers the core inputs and a discovery path for a five-parameter mutation tool with no output schema. It leaves out failure/edge behavior for a destructive rename, 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?

Schema description coverage is 100%, so the schema fully documents all five parameters including context, llm_model, and conversation_id. The description only restates the mapName/newName semantics (name-or-id, case-insensitive is in 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?

States a specific verb (rename) and resource (map), and clarifies that the target can be identified by current name or id. It does not differentiate itself from the sibling rename_layer, which an agent could plausibly confuse it with, 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?

Points the agent at list_maps to discover current names, which is useful routing guidance for the input. However, it gives no when-not conditions (e.g. vs rename_layer) and no prerequisites such as needing an existing map or handling name collisions.

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 readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context: one report per listing per account, a cost of 1 search against the Marketplace limit, broker notification of the reason but not the reporter's identity, and the consequence that 3 account reports hide the listing pending review. These are effects an agent could not derive from the schema or 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 sentences, each front-loading the most decision-relevant information: what to report, when to use it, the rate/account constraints, and the downstream effects. No filler or repetition of structured 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 mutation tool with no output schema and only minimal annotations, the description covers the critical behavioral envelope: preconditions, rate limits, privacy of the reporter, and the state change triggered by multiple reports. An agent has everything needed to call it correctly and 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 description coverage is 83%, so the schema already carries most parameter meaning. The description still adds value by explaining the reason categories in prose (off the market, wrong, not this Broker's listing, spam) and clarifying that only the reason, not the reporter, reaches the broker.

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 (report a Marketplace listing) plus the precise scope of valid targets: off-market, wrong, not this Broker's listing, or spam. It names the sibling tool it depends on (search_public_listings) and is clearly distinguishable from read-oriented siblings like get_public_listing or search_public_listings.

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 activation condition ('Use it only when the user asks to report') and enumerates the qualifying listing states. It does not name an alternative tool or exclusion path beyond that, so it is clear context without full when-not/alternative 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description does add real behavioral value — results are plotted on a live map preview, the return shape is total 'count' plus one page (default 50, max 500), and offset paging terminates when nextOffset is null. That is genuine context beyond the annotations, though it stays silent on things like auth scope, ordering of results, and rate limits.

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?

Well front-loaded: purpose first, then the PREFER-THIS routing, then filter capability, then return shape and pagination. It is long but nearly every sentence adds an operational fact; the filter list is the one segment that overlaps the schema and could be trimmed.

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 22-parameter tool with a nested GeoJSON object and no output schema, the description still leaves nothing essential missing: it states what comes back (count + one page, default 50/max 500), how to paginate, and what filters exist. An agent can call it correctly on the first try.

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 descriptions are already unusually rich (keyword guidance, withinZone trigger phrases, externalIds lookup rationale, conversation_id handling), so the schema carries the weight. The description's filter enumeration (layer, price, acreage, date, keyword, custom field, flagged, polygon) mirrors what the schema documents rather than adding syntax or format detail. 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 (search) and scoped resource ("the connected account's own MappaIQ property data — its listings, sites, comps and quotes"), which distinguishes it from the public-facing siblings. It stops short of naming an alternative tool explicitly, so an agent must infer the boundary from the "own/connected account" qualifier.

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?

"PREFER THIS whenever the user asks to show, pull up, see, find, list or map their properties..." gives an explicit positive trigger with worked examples ('show me 5 biggest Weitzman sites'). It also covers the downstream case in the same breath: for full audit/export, page with offset until nextOffset is null — so both the default and the bulk path are routed.

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 destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context by noting that returned places will appear on the map, which is a visible side effect not captured in 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: purpose first, then trigger conditions with inline examples. No filler, and the most decision-relevant information is 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 an 8-parameter tool with full schema coverage and no output schema, the description covers the return value ('a list of places') and the map side effect. The analytics/context and conversation_id plumbing is fully explained in the schema, so little 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 every parameter including defaults (near defaults to Dallas, limit 5-25) is already documented. The description adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does 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 and resource ('Search for businesses, points of interest, or places on the map') and scopes it to map-displayed results. This distinguishes it from siblings like search_comps and search_public_listings, which target different resources.

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 trigger ('Use when the user asks to find or show places') reinforced by three concrete example utterances. It does not name alternative sibling tools or state when not to use it, so it stops short of a 5.

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 readOnly/non-destructive, but the description adds substantial behavior: full-map exposure ('publishing a map makes the whole map public'), field normalization with broker synonym handling, confirmedDaysAgo semantics (null when undated), co-listing dedup rules, and the explicit absence of phone/email. This is well beyond what structured fields 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?

The purpose and scope are front-loaded, and each clause carries substantive information (dedup, normalization, pagination). The sentences are long and dense, packing several distinct behaviors per sentence, so it reads as a wall of text rather than crisply structured 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 14-parameter tool with no output schema, the description compensates thoroughly: it describes the return shape (all fields as stored, normalized fields, attribution, listedBy, offers), pagination (50/page), and the contact-data gap. Nothing an agent needs to call or interpret results 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?

With 71% schema coverage, the schema documents most params, but the description adds real meaning: keyword matches name/address/notes/city, publicMapId comes from list_public_maps, and the price/acreage/assetClass filters map onto normalized fields. It does not explain limit/offset or the analytics-only params, which the schema already covers.

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 ('Search pins ACROSS THE OPEN MARKETPLACE') and immediately scopes it against siblings: 'the pins of every publicly published map on MappaIQ, not just this account.' An agent can distinguish it from search_comps, find_listings, and list_public_maps 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 gives concrete triggering examples ('what land is publicly listed under $2M around Rockwall') and routes to the right siblings for follow-ups: list_public_maps for publicMapId and get_public_listing for phone/email. It stops short of an explicit when-not-to-use statement (e.g. 'use find_listings for your own account's pins'), leaving that boundary implied.

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 flag destructiveHint=true; the description goes further by specifying exactly what 'remove:true' deletes (the pin's callout) and clarifying that omitted fields/position leave existing state untouched. It doesn't mention permissions or reversibility, but the mutation semantics are disclosed clearly.

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 action and resource, then moves through targeting, fields, position, and removal. Dense but each clause carries operational information; the mid-sentence parenthetical about what a callout is is the only mild padding.

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 9-parameter mutation tool with no output schema, the description covers the essential behaviors: targeting resolution, field ordering, position defaults, and deletion. Return/candidate format is only lightly touched, but nothing critical 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 coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: 'fields' is ordered and omit-to-keep behavior, direction+distanceMiles placement semantics, and compId-over-name preference — all go beyond the field-level docs.

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 specific verbs (add/edit/move/remove) and a precise resource (a callout bubble on a pin), then defines what that resource is. No sibling tool overlaps this function, so an agent can identify it unambiguously.

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 targeting guidance (compId preferred, ambiguous name returns candidates rather than guessing) and states the effect of omitting 'fields' and position parameters. It stops short of explicit when-not-to-use or routing to an alternative sibling, but the conditional behavior is well covered.

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 and destructiveHint=true, so the mutation profile is known. The description adds genuine value by disclosing upsert semantics ('Creates or updates the field'), but it does not say what happens to an existing value on overwrite or whether the write is reversible, which matters for a destructive-flagged 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?

Three short sentences, zero padding, and the scoping constraint is front-loaded before the routing advice. Each sentence carries a distinct piece of information (scope, alternative, upsert behavior).

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 purpose, scope and sibling routing, which is the core need for this 6-parameter tool, and the required analytics/continuity parameters (context, llm_model, conversation_id) are well documented in the schema. It stops short of describing overwrite behavior for a destructive-flagged write, which is the one 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?

Schema description coverage is 100%, so the baseline is 3; every parameter, including context, llm_model and conversation_id, is fully documented in the schema. The description adds no parameter-level detail (e.g. key naming or value format) 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?

States a specific verb plus resource and scope: writes a key/value to a SINGLE record, and explicitly notes it creates or updates the field. It names the bulk sibling by contrast, so an agent can distinguish it from bulk_set_custom_fields 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 an explicit when-to-use-this vs when-to-use-the-alternative rule: single record here, bulk_set_custom_fields for tagging many records, with the concrete anti-pattern ('don't loop this one call per record') 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 cover the write/destructive profile, and the description adds real behavioral context beyond them: the bulk case-insensitive matching semantics, the heuristic that the domain is guessed from the brand name, and the remove:true inverse mode. It omits return behavior and whether changes are reversible, 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?

Front-loaded with the effect and the badge rendering, then the targeting modes, then the domain caveat and the remove flag. Dense but every clause carries actionable information; nothing 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 9-parameter mutation tool with no output schema, the description covers targeting, scoping, domain override, and removal adequately, while the three analytics/meta params are fully documented in the schema. It does not state what the call returns (e.g. how many pins were updated), a minor 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: how nameContains matching works across pins and layers, and concretely why/when to pass `domain` (Chick-fil-A → chick-fil-a.com). This is genuinely additive over the field 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?

States a specific verb+resource+effect: 'Put a brand logo on pins — the pin renders as a badge ... instead of a colored dot.' This is concrete and distinguishable from siblings like set_callout or add_comp 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?

Clearly explains the two targeting modes (one pin by compId vs many by nameContains, optionally scoped to a layer) and when to override the domain guess. It does not name or compare against alternative sibling tools, so it falls short of a 5.

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 and destructiveHint=true, so the safety profile is covered. However, the description adds nothing behavioral beyond the annotations: it does not say whether this is a partial merge (only supplied fields changed) or a full replacement that clears omitted fields — a critical distinction for a 16-parameter destructive update. Given the annotations do the safety work, this is a modest gap, but the merge-vs-replace semantics are left entirely 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?

A single compact sentence with no padding, and the purpose is front-loaded. It is efficient, though its brevity is closer to under-specification than ideal conciseness for a tool of this 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 destructive 16-parameter mutation tool with 44% schema coverage and no output schema, the description is far too thin. It omits update semantics, the effect of omitted fields, and any signal about partial vs. whole-record updates, leaving the agent materially underinformed.

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 only 44%, so most of the 16 parameters (date, name, buyer, notes, price, seller, zoning, acreage, address) carry no documented meaning in either the schema or the description. The description adds zero parameter-level information, leaving a large compensating burden unmet.

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 ('Update properties of a single existing comp/waypoint'), and the word 'single' implicitly contrasts with bulk_update_comps. The title 'Update pin' and the body's 'comp/waypoint' terminology are inconsistent, which slightly muddies the resource identity, but the core purpose is 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 when-to-use guidance, no prerequisites, and no routing to alternatives such as bulk_update_comps (for multiple records) or update_listing (for listings). The agent gets the purpose but must infer the selection conditions from sibling names alone.

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 readOnlyHint=false and destructiveHint=true; the description adds the critical non-obvious side effect that 'Any edit also confirms the listing (Confirmed date = today).' It also mentions the return ('the listing's Marketplace status'). It could say more about what a mutation overwrites, but the side-effect disclosure is genuinely valuable 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?

Three short sentences, front-loaded with the core action and id source, then the side effect, then routing. No wasted words; the 'tell the Broker in one line' instruction is terse and actionable.

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?

Covers purpose, id provenance, side effect, sibling routing, and return value, which is ample for a requires-4-param nested mutation with no output schema. Only slight gap is not elaborating on merge-vs-replace semantics for the nested 'changes' object.

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 details every field (stage enum, price null semantics, name default, etc.), so the description legitimately defers to it. The one derived constraint it reinforces (closing is not a stage) is already in the schema. Baseline 3 for high-coverage 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 ('Change one Listing') and anchors the id to its source tool ('id from find_listings'), immediately separating it from siblings like add_listing or close_listing. An agent can identify the operation 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?

Names the key exclusion explicitly: 'Closing is not a stage: for sold/leased use close_listing,' routing the agent away from a plausible wrong choice. It doesn't enumerate other adjacent options (confirm_listings, update_comp), so it's clear context rather than exhaustive 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.