Bucky

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so 'Repeating the same membership is safe' largely restates idempotentHint. The genuinely additive parts are the 'private folder' scope and the preview-first recommendation, but nothing is said about permissions, failure modes, or what happens when the target already exists in another folder.

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 action and cardinality constraint, then the parameter shape, then behavior and workflow. No sentence is redundant.

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 4-parameter mutation with no output schema, the description covers the action, the target union, idempotency and a preview safety path, which is enough to call it correctly. It omits folder ownership or permission requirements and what the caller gets back on a successful add.

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 50%, and the description compensates on the hardest part: it explains the target anyOf union by telling the agent to supply either savedLotId or projectId, which the schema only expresses structurally. It also flags preview=true semantics in-line. It adds no detail on the required 'context' field, but the schema already spells that out at length.

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 with scope: 'Add exactly one saved lot or project to a private folder.' That precisely separates it from createSavedFolder (makes folders), saveLot (saves lots) and removeSavedFolderItem (the inverse), though it names only listSaved explicitly rather than its nearest sibling.

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 upstream dependency ('savedLotId (a save id from listSaved)') and a recommended workflow ('Use preview=true first'), plus an idempotency note that tells the agent repeats are harmless. It stops short of stating when NOT to use it or naming removeSavedFolderItem as the undo path.

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 read-only/idempotent/non-destructive, yet the description still adds substantial behavior: the four coverage states in the response, the two-step disambiguation flow, the rule that missing facts mean "not surveyed or unavailable, never zero," the distinction between CMHC rental-survey figures and the 2000+ new-build proxy, and per-figure citation obligations with referencePeriod. None of that is recoverable from the annotations or schema.

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 argument-selection rules are correctly front-loaded, but the back half stacks citation boilerplate ("Cite RMS figures as Source: CMHC, Rental Market Survey, October YYYY...", "Cite starts and completions with their own source and period") that is formatting policy rather than tool-selection guidance. Every clause is defensible in isolation, yet the block runs long and mixes invocation rules with output-citation rules.

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 does the work of explaining returns: topic grouping, the four availability states, disambiguation behavior, and the fallback when a place is unmapped. That is enough for an agent to call it and interpret results. The residual gap is that the required `context` parameter and the semantics of `geoDivisionId` versus a name are only implied.

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 20% (only `context` is documented), so the description must carry the load, and it largely does: it states the one-of constraint across cityName / lat+lng / geoDivisionId and the constraint that lat and lng travel together. It never mentions the required `context` analytics parameter, so it does not fully close a 0%-covered required field even though the schema covers that one.

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?

"Public city catalogue inventory" plus "Shows datasets grouped by topic as on file, not loaded yet, unavailable, or not confirmed" establishes the resource and the return shape concretely. The description then rules out adjacent scopes ("not lot feasibility or operator health"), which separates it from the feasibility siblings. It loses a point only because the opening noun phrase is jargon-ish and the verb has to be inferred from later sentences.

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

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

The caller is told the three admissible input modes, the lat/lng pairing requirement, the "never pass a slug" exclusion, and the exact disambiguation loop (multiple matches → user picks → re-call with geoDivisionId). It also bounds the tool against feasibility and against the un-named "recording demand" tool. What is missing is a named sibling alternative; exclusions are stated by negation rather than by pointing at a specific tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description adds the practical consequence — a repeated create produces a duplicate folder rather than updating — plus a safe dry-run path via preview. It leaves out auth/permission requirements and what happens on duplicate names, but it meaningfully extends the annotation set.

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

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

Three short sentences, front-loaded with the action, then the duplicate-creation caveat, then the safe-retry procedure. No filler and nothing 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 create tool with annotations and no output schema, the description covers the main risk (accidental duplicates) and the mitigation. It omits error behavior on duplicate names and permission requirements, which an agent would want before calling in a real workspace.

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 67%, so baseline is 3; the description earns an extra point by explaining why preview exists in workflow terms ('use preview=true first'), which goes beyond the schema's terse 'inspect the request without writing'. The name parameter's constraints (1-120 chars) and the context analytics parameter are left entirely to the schema.

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

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

States a specific verb and resource ('Create a named private folder'), which is clearly distinct from renameSavedFolder, deleteSavedFolder, and addSavedFolderItem. It doesn't explicitly contrast with saveToProject or saveLot, which are the nearest ambiguous alternatives, 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 operational guidance: use preview=true first, and use listSavedFolders to verify an uncertain outcome before retrying. It names the sibling to consult and the situation that warrants it, though it doesn't say when not to use this tool versus other save mechanisms.

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 idempotentHint=true, but the description goes further by disclosing exactly what is destroyed (memberships) and what survives (lots remain saved, projects kept) plus the absence of any restore path. That is precisely the partial-destructiveness context an agent needs before committing.

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, each carrying distinct payload: the operation, the cascade semantics, and the safety protocol. Front-loaded with the verb and resource, 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 destructive tool with no output schema, it covers the essential unknowns: blast radius, surviving data, irreversibility, and the preview safeguard. It omits permission/authorization requirements and whether deletion is scoped to the caller's own folders, which an agent might need.

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 67%, with folderId documented only by a regex pattern, so the description's "by folderId" plus the folder-level scope adds real meaning. "Use preview=true first" also gives preview a workflow role beyond the schema's bare "inspect the request without writing." It stops short of describing what inspect output contains.

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 ("Delete a private folder by folderId") and immediately clarifies the cascade scope: memberships removed, lots and projects kept. It is clearly a delete operation distinct from createSavedFolder or renameSavedFolder, though it never names a sibling explicitly.

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 pre-call guidance ("Use preview=true first") and rules out a recovery expectation ("does not restore deleted folders"). It doesn't contrast against removeSavedFolderItem for removing contents versus deleting the container, so the alternative-selection guidance is implicit rather than complete.

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 provides critical behavioral context by explicitly stating that the tool is a 'pure static lookup' and listing which systems it does *not* interact with (database, geocoder, AI model, etc.), defining its operational boundaries.

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

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

The description is highly dense and efficient. It front-loads the core purpose and follows up with detailed operational constraints, ensuring every sentence provides necessary 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?

Given that the tool is defined as a pure static lookup, the description is extremely complete. It defines the exact input constraints (verbatim status), output constraints (returning the list if unknown), and operational limits.

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 100% schema coverage, the baseline is strong. The description significantly adds value by listing every single possible enum value for the 'status' parameter, removing any ambiguity for the calling agent.

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

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

The description clearly defines the tool's function as explaining a specific 'Bucky coverage or per-fact provenance status' and providing the 'safe next action.' This is distinct from other analysis or retrieval tools in the sibling list.

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?

While it does not compare itself to other tools, it provides strict usage guidelines by requiring a status to be copied 'verbatim' from a feasibility result, defining its precise domain of applicability.

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, yet the description adds auth requirements, the fact that places are compared on a single survey period, pagination behavior via 'truncation.places.nextOffset', the 50-name cap on unknown lists, and the licensing/citation obligation. It also explains a non-obvious semantic: a place missing a filtered value is 'not a match and not a fail'.

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 purpose and the sibling exclusion before descending into parameters and return semantics. Dense and mostly earning its place, though a few sentences pack multiple facts and the parameter enumeration is longer than strictly necessary.

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 fully specifies the return shape: counts { places, matched, excluded, unknown }, matched places with values, unknown places with missing keys, and truncation details. Nothing an agent needs to call or interpret results 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?

Adds real meaning beyond the 75%-covered schema: the concrete preset ids (tight-rental, fast-rent-growth, undersupplied, mli-select-headroom), 'CA has data today' for country, region as 'province code or name', and inclusive bounds for filters. Some of it repeats schema facts (limit default 20 / max 50), which keeps it from a 5.

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?

Opens with a specific verb+resource ('Find which places to look at by their rental market') and clarifies the scope as 'the places Bucky sells (reviewed catalogue places)'. The closing line 'Market data filters places, not lots: use screenLots for lots inside a place' explicitly separates it from the nearest sibling.

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?

States access conditions ('Signed-in only; read scope') and names the alternative for a common confusion ('use screenLots for lots inside a place'). It also tells the agent how to discover valid filter keys ('An unknown key returns the filterable keys'). It does not cover when to prefer presets over filters or when other siblings apply, so not a full 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the two-call pattern and that the output is directional next-step guidance rather than data. It does not say what happens if optional params are supplied on the first call or whether they persist.

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 filler, and the most important instruction (call with no arguments first) is front-loaded before the optional refinement detail.

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 carries the burden of explaining the return value, and 'what this session should do next' stays abstract — an agent cannot anticipate whether it gets prose instructions, tool recommendations, or a checklist. Combined with the unresolved required-`context` conflict, the definition is usable but leaves gaps for a first-contact tool.

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

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

The description explains the sequencing of the three optional enums (they answer the first-call questions on a second call), which the schema alone does not convey. However, it instructs 'Call with no arguments on first contact' while the schema marks `context` as required — a direct conflict that will confuse an agent about whether it can call with zero arguments.

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 concretely that the tool returns 'what this session should do next' and frames the call pattern (first contact vs. second call), which makes the onboarding/guidance purpose clear in combination with the name and title. It stops short of saying outright that it returns the MCP usage guide itself, so the resource is implied rather than named.

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 call sequence: no arguments on first contact, then optionally pass role/market/scale on a second call to answer the first-call questions. There is no realistic alternative sibling for onboarding, so the absence of named alternatives costs nothing.

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

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

Beyond the readOnly/idempotent annotations, it discloses the 12,000-character per-section cap, the truncation contract (`truncated`, `totalChars`, `nextOffset` plus the resume call with `textOffset`), the `missing` result set for unresolved ids, and the substantive caveat that a cited number may still be conditional on frontage, tenure, or adjoining district. That is exactly the behavior an agent needs before relying on the returned text.

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?

Six tight sentences, front-loaded with the purpose and the primary id-based path before the alternate path, pagination, and error case. No filler or restatement 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?

There is no output schema, so the description must carry return-value semantics — and it does, describing markdown content, the truncation fields, the resume protocol, and the `missing` collection. For a 6-parameter read tool this leaves nothing an agent needs unresolved.

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 the mutually exclusive grouping of the two parameter sets ("Or pass..."), which the schema itself never states, plus how `textOffset` is derived from `nextOffset`. It also gives concrete example values for `sectionNumbers` (3.1, 3.2).

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?

"Return the stored bylaw section text behind a snapshot citation" names a specific verb (return), resource (bylaw section text), and scope (behind a snapshot citation). This clearly distinguishes it from the sibling getFeasibilitySnapshot, which produces the citations rather than the text.

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

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

The description gives two concrete invocation paths — copy `sectionIds` from `citations.*.knowledgeSectionId`, or use `geoDivisionId` + `zoneCode` + `sectionNumbers` — and implicitly establishes getFeasibilitySnapshot as the prerequisite. It does not state when this tool is not appropriate (e.g. no snapshot yet, or coverage gaps), but the context is otherwise 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?

Explains why the tool is not read-only/idempotent: 'A live answer uses one site lookup from the monthly plan allowance; `usage` says if it was charged and how many are left' — a cost/rate-limit disclosure the annotations cannot express. It also discloses interpretation hazards ('Missing facts are not surveyed or unavailable, never zero'; 'Envelope numbers are extracted ceilings') that materially affect how results are reported.

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 single-address constraint are front-loaded, and most sentences carry actionable content (status handling, citation formats, conformance semantics). It is dense and long, with citation-format rules and envelope caveats packed into one undifferentiated block, which slightly hurts scanability.

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 takes on responsibility for return-value interpretation and does so thoroughly (status values, missing-vs-zero, citation requirements, lot conformity logic). The `source` parameter's role in attribution is left to the schema, a minor gap for a high-complexity tool.

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 schema already documents all three parameters well, including examples and the `context` privacy constraint. The description only reinforces the `address` constraint (one per call, no search) and never mentions `source` or `context`, so it adds little beyond the schema.

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

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

States a specific verb and resource with scope: 'Look up lot, zone, and building envelope for one street address in Canada or the US.' The 'One address per call; cannot search or compare' clause immediately separates it from batch siblings like screenLots and runFeasibilityAnalysis.

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 rules: call `explainFeasibilityStatus` before interpreting `not_extracted`/`site_specific_schedule`, call `getBylawSection` before treating an envelope figure as available on the lot, and use `getBuckyMcpGuide` for the free allowance check. It also names an explicit don't ('Do not fetch `zone.bylawSourceUrl`').

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses default include=none, per-list return caps with defaults and maxima, that truncation metadata (`total`, `returned`, `truncated`) is supplied for every cuttable list, that ambiguous project names return candidates instead of guessing, and that writes are out of scope. This is exactly the behavioral context the 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?

It is front-loaded with what is loaded, then moves through optional sections, limits, truncation, and the UUID-free path in a logical order with no filler. It is dense but every sentence carries actionable information; the sentence about writes staying on the CLI is the only mild repetition with the `include` schema description.

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 read tool with no output schema, the description adequately conveys both input behavior (include, limits, project resolution) and output shape (envelope sections, truncation metadata), so an agent can call it and interpret the response without additional docs.

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 67% and the two numeric limits have no schema descriptions at all, so the description does real work: it states their default of 20 and max of 50, notes each include list returns up to 20, and explains project-name matching semantics (case-insensitive, exact beats partial, ambiguity lists candidates). The `include` optionality and payload-equivalence with an omitted include are also clarified.

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 names a specific verb and resource ('Load one project') and enumerates the exact contents of the bundle (analysis envelope, agentStatus, document/evidence summaries, memory digest, external_ref). It is clearly distinguishable from siblings like produceProjectReport or uiGetAnalysisStatus, which generate output or report status rather than loading a project context bundle.

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 timing guidance ('Use before composing reports or after scheduling analysis') and points write operations to the Bucky CLI, which implicitly scopes this tool to reads. It also explains the no-UUID path (pass `project`, or call with neither to list projects). It stops short of naming a specific sibling to prefer for a given alternative scenario.

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 carry readOnly/idempotent/non-destructive, and the description adds real value on top: a default page size of 50, a hard maximum of 200, and the fact that folder ids and project stages come back. Pagination cursor/offset behavior is left 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?

Four short sentences, front-loaded with the core action then limits, then parameter guidance, then the disambiguation. No filler or redundant restatement 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?

No output schema exists, and the description does describe the shape of results (folder ids, project stages, lot entries with two distinct ids), which is what an agent needs. Offset semantics and the meaning of 'project stages' remain thin.

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

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

Schema coverage is only 25% (only context is documented), so the description must compensate and largely does: it explains limit's default and cap, folderId's purpose, and the savedLotId vs lotId distinction. The offset parameter goes unexplained.

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 the signed-in user's saved lots and projects.' The closing line 'A saved lot is not a project' preempts a likely conceptual confusion, though it never names the nearest sibling listSavedFolders to distinguish 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?

Gives one concrete usage instruction ('Use folderId to read one private folder') and a downstream hint about reusing the id as savedLotId. It does not say when to prefer this over listSavedFolders or when to fall back to unsaveLot/saveToProject, leaving sibling selection implicit.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context on top: sort order, that rows include item counts, and that folders aggregate lots and projects from different places. It does not disclose whether more rows exist beyond the limit or how paging behaves, which is the remaining behavioral gap.

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 scope; the padding and counting details follow naturally. The final sentence on folder contents earns its place by clarifying what a folder is.

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 readOnly annotations and no output schema, the safety and return-shape burden is light, and the description covers ordering and counts. But pagination semantics (offset, whether a total is returned, what an empty list looks like) are missing, leaving an agent unable to page confidently.

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

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

Schema coverage is only 33% - just the context analytics parameter is documented. The description restates limit's default and maximum (already in the schema, so no added value) but says nothing at all about offset, which is the parameter an agent needs to understand to page through folders. The low-coverage case requires the description to compensate and it does not.

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 the signed-in user's private folders') plus the ordering and returned fields (most recently used first, with item counts). It implies the user-private scope that separates it from the broader listSaved sibling, though it never names that sibling explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is the browse entry point for folders that feed addSavedFolderItem/removeSavedFolderItem, but nothing says when to prefer it over listSaved or how to page through results. No exclusions or prerequisites are given.

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 cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description still adds non-obvious behavior: the call is free and requires no sign-in, it returns presence status (found / partly on file / not on file) rather than values, and the lot outline is an unscaled shape. This prevents an agent from misreading the result as real dimensional data.

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 two facts an agent needs most (free, no sign-in), then scope, then the negative space (no values returned), then routing to the sibling. Every sentence carries distinct information; nothing is repeated from the schema.

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, so the description must carry the return semantics — and it does, spelling out the three coverage statuses and explicitly warning that no zone codes, heights, setbacks or areas come back. Combined with the geographic scoping and the sign-in routing, an agent has everything needed to call it 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 address format and the analytics-only 'context' parameter are already documented. The description still adds a real constraint the schema lacks: exactly one address, restricted to Canada or the US. It adds nothing about the 'context' parameter, but the schema handles that 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?

States a specific verb+resource: a free, no-sign-in preview of what coverage/zoning facts exist for one street address. It enumerates the facts checked (lot boundary, zone, height, density, setbacks, permitted uses, overlays, parking) and explicitly contrasts itself with getFeasibilitySnapshot, so an agent can separate it from siblings 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?

Gives an explicit use condition — 'when the user is not signed in and asks what they can build at an address' — plus the alternative and its consequence: 'For the numbers, call getFeasibilitySnapshot. That call asks the user to sign in.' Both the when and the when-not 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?

The description carries full behavioral disclosure: meter spend on records.exports, irreversibility of export, the listing fallback, and the concrete return shape (signed download URL, never PDF bytes). This goes well beyond the {readOnlyHint:false, destructiveHint:false, openWorldHint:true} annotations; the 'irreversible' note is consistent with an additive, non-destructive export rather than a contradiction.

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 purpose, then progressively discloses the decisions that matter (project selection, preview vs confirm, spend/return). Every sentence earns its place; no redundant restatement 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?

Strong for a 9-parameter mutation tool with no output schema — return format, cost, and reversibility are all covered. The remaining gap is the opaque `request` parameter and the unexplained content-shaping params (audience, detail, planName).

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

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

The description adds real meaning for the key params (projectId/project resolution, the preview/confirm coupling) and even documents the no-project fallback that the schema lacks. However, it leaves `request`, `audience`, `detail`, and `planName` unaddressed, and `request` has no schema description at all, so the agent cannot infer its role.

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: 'Compose a project report PDF,' which clearly distinguishes this from analysis/context siblings. However, it does not explicitly compare itself to any sibling tool, leaving that differentiation to inference.

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 defines the operating modes: pass projectId or project, get a project listing with no spend if neither, preview=true to compose without spending, and confirm=true to export and spend. An agent knows precisely which path to take for each goal.

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, idempotentHint=true) by explaining exactly what is and isn't changed: "it hides no lot, changes no alert and teaches the search nothing." It discloses auth requirements, the 25-per-search cap, dedup behavior via skipped=already_flagged, and enumerates the full skipped vocabulary so the agent can interpret partial failure.

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 human-confirmation caveat are front-loaded, then progressively finer detail (params, non-effects, return shape, limits). It is a single dense paragraph that is longer than the minimum, with a few sentences that duplicate the schema, but almost every sentence carries operational weight.

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 fully by documenting the return shape: results with { lotId, proposed, flagId } or { lotId, proposed: false, skipped } plus the pending/limit object. Combined with the auth, limit and side-effect disclosures, an agent has everything needed to call this correctly and interpret the response.

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 75%, and the description adds real value by stating provenance ("lotId comes from screenLots with that profileId") and that evidence is a short free-text observation, not a verdict. Some content (the reasonCode list, the 1–25 bound, preview behavior) merely restates the schema, so it adds lineage rather than fully new semantics.

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: "Suggest that results of one saved search are not a fit", and immediately clarifies the human-in-the-loop nature ("for the user to confirm or reject on the result row"). It explicitly disambiguates from sister tools (submitBuckyFeedback) and names screenLots as the source of lotId, so an agent can distinguish it from siblings 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?

Strong operational guidance: signed-in only, write scope, preview=true proposes nothing, "never propose it again" for declined lots, and at the 25-per-search limit "wait for the user to answer". It names an explicit alternative to avoid (submitBuckyFeedback) and a prerequisite source (screenLots). What it lacks is an explicit trigger statement for when a lot should be judged "not a fit" beyond the reason codes.

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=false and idempotentHint=true; the description adds the crucial side-effect context that 'The lot stays saved and the project is kept,' which is exactly the behavioral detail annotations cannot express. It does not cover failure cases, such as what happens if the item is not in the folder or lacks permission.

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 action and scope, then the parameter guidance, then the safety step. 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 mutation tool with no output schema, the description covers scope, parameters, side effects, and a preview path, which is close to complete. Remaining gaps are error/idempotency specifics and folder-membership preconditions.

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

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

Schema coverage is only 50%, and folderId has no schema description at all, but the description compensates by explaining that 'target' is a discriminated object taking either savedLotId or projectId, which the schema alone conveys only structurally. This is meaningfully more than the schema 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?

Names a specific verb and resource ('Remove exactly one saved lot or project from a private folder') and the 'exactly one' scoping distinguishes it from bulk operations. It also implicitly separates itself from deleteSavedFolder by noting the item is merely detached from the folder, though it never names that sibling explicitly.

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 preview=true first' gives an explicit precondition for safe invocation, and the two target variants (savedLotId or projectId) tell the agent which branch of the union to use. It stops short of stating when to prefer deleteSavedFolder or unsaveLot instead.

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

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

Annotations already declare the safety profile (not read-only, non-destructive, idempotent), and the description adds the dry-run preview workflow, which is genuinely useful. It does not disclose permissions required to rename, whether the old name is recoverable, or what happens to folder contents, so it adds only moderate value beyond annotations.

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

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

Two tight sentences with no waste; the operation and its identifier are front-loaded, and the preview recommendation follows immediately.

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 no output schema and three required parameters, the definition plus annotations cover the essentials: what changes, how to target it, and how to dry-run it safely. Minor gaps remain around permission requirements and the unexplained name length constraint.

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

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

Schema coverage is 50%: context is fully documented in the schema and preview is described identically there, while name and folderId carry no schema descriptions. The description identifies folderId as the folder selector and reinforces preview, but adds nothing about name constraints (1-120 chars) or the analytics-only nature of context.

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 ("Rename a private folder") and names the identifier (folderId), which is clearly distinct from createSavedFolder, deleteSavedFolder, and listSavedFolders by verb alone. It does not explicitly contrast with siblings, 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?

Gives actionable usage guidance: supply name, and call with preview=true first to inspect the request before writing. It does not state when to prefer an alternative tool or any preconditions (e.g. ownership of the folder), which keeps it below 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?

Adds substantial context beyond annotations: non-blocking return, the full agentStatus enum, a receipt id, and the key irreversibility warning that a queued run cannot be cancelled from MCP. That irreversibility caveat is exactly the kind of thing destructiveHint=false and idempotentHint=false cannot convey on their own, and it is consistent with them.

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 in the first sentence, then layers the conditional parameter behavior, return contract, and polling guard in descending order of importance. No sentence is filler and nothing is repeated.

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 does the needed work by naming the return fields and their possible values. It leaves unspecified what the analysis itself yields and how a typical run duration should be communicated to a user, which matters for a non-blocking operation.

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 carries the per-parameter detail, but the description adds the cross-parameter semantics that matter: projectId vs project name precedence and the neither-supplied branch. The `context` analytics parameter is left unmentioned in prose, which is fine given the schema documents it 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 and resource ('Enqueue a fresh deterministic analysis run for a saved project') and implicitly separates itself from siblings like getFeasibilitySnapshot and explainFeasibilityStatus, which read rather than enqueue. The agent can tell what it produces (a queued run) 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 routes the follow-up check to getProjectContext and warns against using it as a poll endpoint more than once per 15 seconds, and describes the no-identifier fallback (lists projects, nothing queued). It stops short of saying when not to enqueue at all, e.g. when agentStatus is already 'current' and a snapshot read would suffice.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the description isn't carrying the safety burden. It still adds real value by spelling out that no project is created and no analysis is run, and by giving the idempotency hint concrete meaning ('Saving it again keeps the same save').

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 its scope, followed by the identifier source and the preview workflow. Nothing is redundant or padded.

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 covers the essential call contract: single-parcel save, idempotency, no side effects beyond saving, and a dry-run option. It could say slightly more about where the saved lot surfaces (listSaved/saved folders), but nothing critical to invoking it 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 67%, with lotId carrying only format/pattern and no prose. The description compensates by telling the agent where a valid lotId comes from (a screenLots lot or assembly lot) and by restating the dry-run meaning of preview=true.

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 names a specific verb and resource ('Save one parcel by lotId') and bounds the scope by excluding project creation and analysis runs, which separates it from saveToProject and runFeasibilityAnalysis. It never names those siblings outright, so the differentiation is inferred rather than explicit.

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 a concrete prerequisite ('Copy lotId from a screenLots lot or assembly lot'), states the repeat-call behavior, and recommends 'Use preview=true first'. What's missing is an explicit statement of when to choose saveToProject instead of this tool for project-scoped saving.

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

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

Annotations already establish readOnly=false, destructive=false, idempotent=false, openWorld=true, but the description adds real value beyond them: preview returns a field-level diff and writes nothing, a write returns a receipt, results report source truncation and attached count, and changes are not reversible on this surface. The 'not reversible' caveat sits in mild tension with destructiveHint=false without quite contradicting it (attaching parcels adds rather than destroys data). Permission or auth requirements and failure modes are not disclosed.

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?

Dense and front-loaded: the action enum and ID routing come first, then mode-specific constraints, then preview and return behavior. Every sentence carries facts, though the middle section packs polygon, parcelExternalIds, radiusM, truncation, preview, and receipts into a single run-on stretch that is harder to scan than the opening.

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 mutation with no output schema, the description covers the critical call paths and return signals (diff, receipt, attached count, truncation). Remaining gaps are per-action parameter applicability and error behavior, which for openWorld=true calls an agent would want spelled out.

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 81% schema coverage the schema carries most of the load, but the description still adds meaning: polygon vs parcelExternalIds vs radiusM are explicitly exclusive, the 500-parcel selection cap is stated, and parcelExternalIds are sourced from lot.parcelExternalId on getFeasibilitySnapshot. It does not explain which of the sixteen parameters belong to which action (name, address, externalRef, sectionUuid, idempotencyKey are left to the schema).

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

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

The description immediately names the three concrete operations (create, attach_parcels, attach_reference) and what each touches, so the agent knows exactly what resource is being acted on. It falls short of a 5 because it never distinguishes itself from the write-side siblings (updateProject, createSavedFolder), leaving the agent to infer boundary cases such as modifying an existing project.

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 routing rules: pass projectId or project, and with neither the call degrades to listing projects and writing nothing. It also names mutually exclusive parameter combinations (polygon cannot be combined with parcelExternalIds or radiusM) and offers preview=true as the non-writing alternative. This is when/when-not guidance with alternatives, not just context.

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

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

Beyond the annotations, it discloses that save=true writes a saved list, counts against the plan list limit, and returns a CSV link; paging is read-only and saves nothing; search execution history is recorded; hygiene defaults apply; and not_available filters must be reported. These are meaningful behavioral details that annotations alone do not 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 description is front-loaded with purpose, but it then becomes a dense, run-on block covering returns, candidate assessment, save workflow, paging, IDs, and quotas. Most sentences carry information, but the lack of paragraph breaks and the cryptic clauses make it harder to scan than necessary.

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 complex 13-parameter tool with no output schema, the description does a good job describing the returned fields (countOutcome, screeningRunId, verdicts, totalMatches, candidates, suggestions, savedMatches, CSV link) and the save/paging behaviors. Some return structures remain only loosely specified, but the core behavioral contract is 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 baseline is 3. The description adds valuable cross-parameter workflow semantics: city/geoDivisionId must be paired with thesis or criteria, profileId is an alternative saved-list mode, save requires explicit approval, and page.next drives paging. It stops short of fully explaining every nested criteria interaction, but it meaningfully exceeds the schema.

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

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

The opening sentence states a specific verb and resource (find lots) and scope (one live Bucky city matching a list). It is clearly a screening/search tool, and the cross-references to saveLot, getFeasibilitySnapshot and saveToProject further distinguish it from 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?

The description gives clear invocation context: pass city or geoDivisionId with thesis, criteria, or both; or pass profileId; save only after explicit approval; use page.next when truncated. It does not explicitly name when to choose this over sibling tools like cityInventory or findPlacesByMarket, so it lacks exclusions/alternatives for 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 say openWorld and idempotent; the description goes well beyond them by naming the exact fields made public, the prerequisite (a build lot with a centroid, not address-only), and the asymmetry that unlisting 'does not un-share anything already collected while it was public.' That last point is a real irreversibility caveat an agent cannot get from destructiveHint=false.

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, then scope, prerequisites, safety gate, and undo — a sensible order. It is dense rather than padded, though lines like 'A client, a friend, or a private residence is theirs to publish, not yours' spend words on tone that a shorter imperative could carry.

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 still tells the agent what to expect back: preview returns current state, the exact pin, and privacy warnings; the result carries an `undo` field. Combined with the publish-set and undo semantics, an agent can invoke this correctly and interpret the response.

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 semantics the schema lacks: the neither-identifier behavior (list projects, publish nothing) and the preview/write-nothing contract. It restates `project` and `projectId` matching rules already in the schema, which caps it below 5.

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 pair and resource ('Put a project on the public Bucky map, or take it off') that no sibling tool shares — none of the saved-folder, feasibility, or report tools touch public publication. It also defines the publishing scope (centroid, name, zone, typology, lifecycle) so an agent knows exactly what the operation changes.

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 between `projectId` and `project`, an explicit no-identifier fallback ('with neither, the result lists their projects and nothing is published'), an explicit preview-first path, a human-approval gate for non-public sites, and an explicit undo path ('call again with `listed` set to the opposite value'). This is when-to-use and when-not guidance at a high standard.

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, destructiveHint=false, openWorldHint=false and idempotentHint=false, but the description adds genuinely non-obvious behavior: the server asks the MCP client to render the form, and nothing persists unless the human accepts it. That is the key safety fact an agent needs. It stops short of covering retry/deduplication behavior, which is stranded in the submissionId parameter 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?

Four short sentences: what it does, when to call it, what happens on the server, and the exclusion. The exclusion is placed last as a guard rather than buried mid-paragraph, and nothing is repeated.

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 three-parameter tool with complete schema coverage and no output schema, the description covers purpose, trigger conditions, the human-in-the-loop flow, and the no-persistence guarantee. An agent has everything needed to decide to call it and what to expect afterward.

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 three parameters are already documented in structured form, and the description adds nothing about them. Baseline 3 applies since the schema carries the full burden, including the idempotency semantics for submissionId.

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: 'Open a human-reviewed feedback form and submit it to the Bucky product team.' No sibling tool does anything similar, and the human-reviewed framing distinguishes it from any programmatic reporting path.

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 activation conditions ('only when the user explicitly asks to send feedback, report a problem, suggest an improvement, or praise something') and an explicit exclusion ('Do not use for silent agent self-reporting'). Both the when and the when-not 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral information the annotations cannot carry: it returns a single field, and it is cheap enough to poll. It stops short of saying what values agentStatus can take or what happens for a project with no analysis.

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 filler, with the return scope and the cost hint front-loaded ahead of the routing instruction. 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 trivial two-parameter read tool, the definition covers purpose, cost, output shape and the correct alternative, and the annotations cover safety. The remaining gap is minor: no indication of the possible `agentStatus` values or behavior on a project without an analysis run.

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

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

Schema coverage is 50%: `context` is fully documented in the schema, while `projectId` has only a UUID format. The description's 'for a project' weakly signals projectId's role but adds no format or selection guidance. Baseline 3 is appropriate since the schema does half the work.

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 (return only the analysis `agentStatus` for a project) plus an explicit scope limit ('only'). It also names the sibling it should not be confused with (getProjectContext), so an agent can route correctly 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?

Provides an explicit when-not/alternative: it is 'Used by the Bucky app view; the model should call getProjectContext instead.' The polling cost cue ('cheap enough to poll') gives an additional condition under which this tool is appropriate.

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

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

Beyond the destructiveHint=true and idempotentHint=true annotations, the description discloses three important facts: the unsave cascades to every saved folder, projects are preserved, and the action is irreversible because there is no undo. As a result, the agent knows the extent of the side effects and the data that survives.

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

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

It is three short sentences with no filler. The scope and cascade effect come first, then the recommended preview workflow. Every sentence adds new 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 destructive mutation with no output schema and annotations that already cover safety, the description supplies the missing impact details and the preview-first requirement. The only gap is post-condition behavior on invalid or already-unsaved lotIds, which the description does not cover.

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 67%: context and preview are already documented in the schema, so the description's only contribution is behavioral framing, not parameter meaning. The description does not explain what a lotId identifies or what happens when it is unknown or already unsaved, so a 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?

The description uses a specific verb and resource: 'Unsave one parcel by lotId', which makes it clear this is the inverse of saveLot. It also makes clear that the operation only affects the saved-lot entry, not the project, so an agent can distinguish it from saveToProject or removeSavedFolderItem.

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 states a concrete prerequisite workflow: 'Use preview=true first', and it states an exclusion: 'this MCP tool does not provide Undo'. This is strong guidance, though it never names or explicitly routes to a sibling such as removeSavedFolderItem when the agent only wants to detach from a folder.

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 non-readonly, non-destructive, idempotent, open-world; the description adds real behavior beyond them: preview returns a field-level diff and writes nothing, a write returns a receipt, undoOperationId restores captured prior fields, and ambiguous name matches list candidates rather than guessing. That is exactly the mutation-safety context an agent needs.

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 tight sentences, front-loaded with the patched fields, then identification rules, then preview/undo semantics. No filler and no repetition of schema text.

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

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

With eight parameters, no output schema, and a mutation entry point, the description still covers identification, dry-run, receipt/undo, and return shape ('a write returns a receipt'). Nothing an agent needs 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 description coverage is 88%, so the baseline is 3; the description additionally explains the projectId-vs-project decision, the preview-plus-undoOperationId interaction, and the no-identifier listing fallback. Minor gap: it does not say whether name/lifecycleStatus/externalRef are partial-patch optional or wholesale replacements.

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

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

Names a specific verb and resource plus the exact patchable fields (name, lifecycleStatus, externalRef), and adds an explicit scope exclusion ('Does not archive or delete'). An agent can tell this apart from renameSavedFolder/deleteSavedFolder/saveToProject style siblings 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 explicit routing rules: use `projectId`, or `project` with the spoken name, and states the fallback behavior when neither is supplied (lists projects, writes nothing). Also states preview=true and undoOperationId call conditions and the archive/delete exclusion.

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