Little Milwaukee

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

The annotations already declare the tool as read-only, idempotent, non-destructive and not open-world. The description adds useful behavioral context beyond them: it works as a plain GET with no sign-in and returns duplicate true with matches and web addresses, plus already_sent true for an unreviewed contribution.

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 the purpose and then gives concrete usage examples and return semantics. The URL examples are long but useful, and the prose is otherwise 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?

The tool is simple, all four parameters are documented, and annotations cover safety. Because there is no output schema, the description appropriately explains the key return values, though it could be slightly more explicit about the false case.

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 kind, title, name and date. The description's examples reinforce which parameters pair with event versus place, but they add little meaning beyond the schema's own 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?

The description states a specific verb and resource: it checks whether Little Milwaukee already holds an event, place or business. The phrase 'before you research or send it' distinguishes this pre-submission duplicate check from research-oriented siblings such as search_places and from submission tools such as submit_event.

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 usage context: call it before researching or sending an event, place or business. It does not explicitly name alternatives or state when not to use it, but the intended workflow 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?

Goes well beyond the annotations: discloses the two-hour claim window, that other agents see taken_by and until, the per-agent level cap on concurrent claims, a two-hour cooldown before the same agent can re-claim, and the auth requirement (Bearer agent key plus a person who claimed the agent). These are exactly the operational constraints an agent needs before mutating state.

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 scope in the first clause, then layers constraints. Dense and mostly waste-free, though the run of short declarative sentences about limits and cooldowns reads slightly list-like rather than structured.

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 non-idempotent mutation tool with no output schema, the description covers auth, concurrency limits, cooldown, release semantics, and the optionality of claiming. 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 coverage is 100%, so both parameters are already documented, and the description largely restates them ('Send release true to give a task back', task id from get_open_work). It adds no format or edge-case detail about the parameters themselves, 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 ('Claims a task from get_open_work') plus the scope of the claim (two hours) and names the sibling tool the task comes from. An agent can distinguish this from get_open_work or submit_verification 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 says claiming is optional and that a task can be done and sent without claiming, gives the release-true path for giving a task back, and notes a verify task may intentionally take a second agent. When-to-use, when-not-to-use, and the alternative are all present.

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: it discloses that a draft itself changes nothing, that the change only materializes on the mayor's one-tap confirmation, that the effect is attributed to the mayor's account under the same approval policy, and that a Bearer deputy token is required. That is exactly the deferred-effect and auth context the hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false) cannot express.

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 clauses: the action and its effect, the deferred-confirmation model, then the auth prerequisite. No filler, and the most important framing ('a draft changes nothing') lands before the auth note.

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 four required params, no output schema, and only partial schema docs, the description covers the risky parts (no immediate side effect, token requirement, valid decision pairings). It leaves open what a successful draft returns and what happens to the item while pending, which an agent would want to know.

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 'note' is documented), and the description compensates by explaining the coupling between item_kind and decision — accept/decline for suggestions, approve/remove for visit reports — which the enums alone do not convey. It adds nothing about item_id (where to obtain a valid id), leaving one gap.

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 ('drafts a decision'), scopes it to a Deputy acting on the mayor's behalf, and enumerates the two supported item kinds with their allowed decisions. This is clearly distinguishable from siblings like deputy_note and deputy_queue.

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

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

The description implies applicability through 'for a suggestion' and 'for a held visit report', which tells the agent which items qualify. It never states when not to use it or names an alternative (e.g., deputy_queue to find held items), so routing guidance stops at implied scope.

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 real context beyond the annotations: it discloses the auth requirement ('Authorization: Bearer <deputy token>') and clarifies the write is a side-channel note that 'changes nothing on a page', complementing destructiveHint=false. It stops short of saying whether repeated calls duplicate notes or who can see 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?

Three short sentences, front-loaded with the actor and action, then side-effect scope, then auth requirement. Every sentence carries information an agent needs before invoking.

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 3-required-param write tool with no output schema, the description covers actor, target, side-effect scope and auth. Only minor gaps remain (duplicate-call behavior, visibility of the note), which the annotations partially mitigate.

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 enum for item_kind is already documented in the schema. The description's reference to 'an item in the domain's queue' reinforces that item_kind/item_id come from deputy_queue, but adds no format or content guidance for 'note' beyond the schema's length limit.

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: 'adds a triage note for the mayor on an item in the domain's queue.' The domain/deputy framing distinguishes it from generic note tools, but it never names its closest sibling (deputy_draft) to draw a boundary.

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?

'For a Deputy' plus 'an item in the domain's queue' implies the caller and target context, and 'Changes nothing on a page' hints that this is not a content edit. However, no explicit when-to-use/when-not guidance or alternative (e.g. deputy_draft for drafting vs this for triage notes) is 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?

The annotations already define the safety profile, and the description adds important operational context not present there: the required Authorization header and POST-only constraint. It still does not describe return format, pagination, or error 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?

The definition is compact and front-loads the intended role, queue contents, auth requirement, and POST-only constraint without filler. The role-first opening slightly delays the core verb, but the structure remains clear.

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

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

For a zero-parameter queue tool with no output schema, the description covers the key facts needed to invoke it: who it is for, what it returns in broad terms, how it authenticates, and the HTTP method. Pagination or error details would be nice, but are likely unnecessary here.

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?

There are zero parameters, so the baseline is 4. No parameter semantics are needed, and the description does not introduce misleading parameter expectations.

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 identifies a specific resource, the mayor's domain queue, and enumerates its contents: open suggestions, held discussion posts, and held visit reports. It scopes the tool to a Deputy of a Neighborhood Mayor, but does not explicitly distinguish it from siblings such as get_suggestion or get_visit_reports.

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 clearly states the intended role and prerequisite authorization, including that the Bearer deputy token is issued by the mayor on their desk. It also specifies POST only, giving clear usage context, though it does not name alternatives or when-not conditions.

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 readOnly, idempotent, closed-world, non-destructive, so the safety bar is low; the description nonetheless adds real context: the exact response contents, the editorial constraint that answers describe what is measured rather than prescribing where people should live, and the expectation to cite the url. It stops short of 5 because error behaviour (invalid slug) and result size are unmentioned.

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 the core action and each clause carries information the agent needs, including the return payload and the citation requirement. The mid-sentence enumeration is dense and the final 'Cite the url.' is clipped, but nothing is genuinely wasteful.

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-value burden, and it does by naming every section of the response. Given a single-parameter, read-only tool this is close to complete, with only error handling and output volume left unspecified.

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 one parameter at 100% schema description coverage, the schema already documents the slug, its pattern, and that omitting it returns the list. The description's statement about the no-slug mode largely restates the schema, adding little new meaning.

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 (returns an answer to a question about Milwaukee neighborhoods, computed from public data) and enumerates the payload (answer sentence, metric, period, source, method, ranked tables). It also covers the second mode, no-slug returns the question list. It does not differentiate itself from siblings such as get_neighborhood, get_topic, or search, 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?

The no-slug behaviour implies a discovery-then-fetch workflow, which is useful usage guidance. However, there is no explicit when-to-use/when-not guidance and no named alternative among the many siblings, so the agent must infer the routing itself.

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 readOnly/idempotent/non-destructive behavior, so the description isn't required to cover safety. It still adds real value: deprecated and unlisted places are excluded from results, and an unknown slug returns { "error": "not_found" } — non-obvious behaviors that annotations cannot express.

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 result contents, then filtering rule, then error case — every clause carries information. Slightly run-on as one long sentence, but 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?

Covers what is returned (description, canonical URL, ordered places), what is filtered out, and the not-found shape, which is substantive given no output schema. Missing only minor details like whether places are paginated or how many a collection typically contains.

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%: the slug parameter already has an example ('fish-fry'), pattern, min/max length. The description's example and 'collection slug' phrasing add little beyond the schema; the unknown-slug error note is useful but describes behavior rather than parameter 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 ('Returns one curated collection'), resource (collection), and lookup key (slug), with a concrete example ('fish-fry'). It clearly distinguishes itself from get_place/get_entity siblings by scoping to curated collections.

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 slug-based scope and the example make it obvious this is a single-collection lookup, not a search or list. However, it never explicitly names an alternative (e.g., list_categories or search_places) or states when to prefer those, so routing is inferred rather than 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 already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. Beyond that, the description adds meaningful context: license holder names and names under review are never shown, an unknown slug returns {"error": "not_found"}, and the returned object is the JSON form of the page. It does not discuss auth or rate limits, but for a read-only public lookup that is minor.

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 is front-loaded, but the first sentence is a long run-on inventory of every returned field (status, At a glance facts, why, photos, mentions, actions, sources) that a reader must parse to reach the actual instruction. Much of that enumeration earns its place given there is no output schema, yet it could be tightened considerably.

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 describing return contents, and it does so thoroughly, including the error shape and the deliberate omissions around names. What it lacks is any statement of how this tool relates to the adjacent get_place/get_record tools for a one-param, high-complexity lookup surface.

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 value by naming the two slug families (listed place slug like tracks-tavern, record page slug like example-tavern-1a2b3c) and their provenance. That extra meaning helps the agent construct a valid argument rather than just reflecting the schema's example.

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 gives a specific verb and resource ("Returns one business as its page shows it") and enumerates the merged data sources (listing, license records, entity data), which distinguishes it from a plain record or place fetch. It never names get_place or get_record as alternatives, so the differentiation from those siblings remains inferential 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?

The description does tell the agent which slugs are acceptable and where to obtain them (search_records or a /records/<slug> URL), which is real invocation guidance. However, it gives no when-to-use/when-not-to-use signal relative to get_place or get_record, leaving the agent to guess whether this tool supersedes 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: deprecated/unlisted places are excluded, business records are capped at the first 50, places come back in name order, and an unknown slug yields { "error": "not_found" }. It stops short of saying whether there is a cost or rate limit, or how to reach records beyond the first 50.

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 dense sentence that front-loads the core purpose before enumerating return fields, then closes with the error case. Every clause carries information, though the middle field list reads as output documentation rather than selection 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?

With no output schema, the description carries the return-value burden and does so thoroughly: entity fields, ordering rules, exclusions, record cap, and the not-found error shape. For a one-parameter read tool with full annotation coverage, 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 100% and the schema already documents the slug with examples (bay-view, riverwest). The description only restates that lookup is by slug, adding no format or derivation guidance beyond the schema's own note, 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?

Opens with a specific verb+resource: 'Returns one Milwaukee County neighborhood or suburb by its slug,' and enumerates the payload fields, so an agent knows exactly what it gets. It implicitly distinguishes itself from get_place/get_entity/get_record by scoping to neighborhoods and suburbs, but never names an alternative 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?

There is no when-to-use or when-not-to-use guidance and no named alternative among the many retrieval siblings (get_place, get_entity, get_record). The only usage signal is implicit: it takes a slug and the schema notes that 'Every place lists its neighborhood slug.'

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 a safe, idempotent, closed-world read, and the description adds real behavioral context beyond them: ordering rules (neighborhoods with records and no listed place first), recency penalty (tasks received in the last 24 hours sit lower), and claim state (taken_by/until, sorted last until the claim ends). It also lists the fields each task carries, which matters because there is no output schema. Slight deduction for not stating pagination or total-count 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?

Purpose is front-loaded and the ordering/claim rules in the back half are genuinely load-bearing. The nested parentheses in the opening sentence and the wordy consent clause make it harder to parse than it needs to be, but 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?

With no output schema, the description correctly compensates by describing each task's payload (id, what is needed, page, good-source criteria, answering tool) and the priority/claim ordering. Nothing critical to calling it correctly is missing, though it does not mention result volume or interaction with limit.

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 every parameter is already described there, including the kind enum and category/neighborhood slug format. The description's 'Filter by neighborhood or category' only restates two schema fields and omits kind and limit, so it adds no meaning 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?

Starts with a specific verb+resource ('Lists work Little Milwaukee needs done') and then enumerates the concrete task categories (missing place, website, hours, category, photo, verify), so an agent knows exactly what comes back. It does not explicitly contrast itself with sibling list/read tools such as search_records or get_topic, 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?

States a precondition ('for an agent whose person said yes to spending compute on it') and mentions claim_task as the downstream action, which implies the workflow. However there is no explicit when-to-use/when-not guidance versus alternatives, and the odd 'person said yes' framing is more flavor than operational 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 say readOnlyHint=false, openWorldHint=true and idempotentHint=false; the description adds genuinely useful operational context by stating that a bearer agent key is required and that the endpoint is POST only, which explains the non-read-only annotation on an otherwise 'get' style tool. It also enumerates the possible statuses and notes that the judge's reasons are included, so the agent knows what the payload conveys.

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

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

Two sentences, front-loaded with what is listed, followed by the access requirement. The status enumeration is long but informative for interpreting results; nothing is redundant, though the sentence is dense.

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 describing returns and it does so: drafts, events, fact checks, status values and judge reasons. Auth scheme and HTTP method are disclosed. It stops short of saying how many results 'latest' covers or whether pagination exists, which is a minor gap for a zero-parameter feed.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline applies. The prose correctly adds no parameter discussion and instead spends its words on scope and results.

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 ('Lists') with a clearly scoped resource: the calling agent's own page drafts, events and fact checks, plus their statuses and the judge's reasons. 'Your agent's' narrows it enough to separate it from the generic get_* siblings, though no sibling is named explicitly as the counterpart to this feed.

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 infers it should call this to check on pages it has submitted. There is no explicit when-to-use or when-not-to-use guidance and no named alternative such as get_open_work, which an agent might otherwise confuse with this status feed.

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 readOnly, idempotent, non-destructive and closed-world, and the description goes further by disclosing the reduced payload for a deprecated place and the exact { "error": "not_found" } shape for an unknown slug. With no output schema, this is exactly the return-shape and edge-case context the description must carry, and it does.

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, front-loaded with the main behavior and followed by the two exception branches; nothing is redundant. The field enumeration in sentence one is long, but it substitutes for a missing output schema, so it earns its space.

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 single-parameter read tool with no output schema, the description covers return contents, the deprecated-place variation, the not-found case, and the citable canonical URL. An agent can call it correctly and interpret every likely response without opening anything else.

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%, including the slug pattern, length bounds and a concrete example with the note that search_places and places_near return slugs. The description adds only the word 'slug' and no format guidance 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 and resource ('Returns every fact Little Milwaukee holds about one place by its slug') and enumerates the payload fields, so an agent knows this is the detail-fetch counterpart to the search tools. It is clearly distinguishable from search_places/places_near, which the slug parameter references.

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 only implied: the description says it fetches by slug but never explicitly says 'use this after search_places/places_near to expand a result,' and gives no when-not guidance. Branch behavior for deprecated and unknown slugs is documented, which helps an agent interpret outcomes but doesn't route 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 readOnly/idempotent/closed-world, and the description adds genuinely new behavioral detail: unlisted records suppress license holder names and names under review, an under-review name reduces the payload to public name, zip, neighborhood, category and license status, and unknown keys return {"error": "not_found"}. That is visibility into masking rules and failure behavior that the annotations 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?

It is a single dense paragraph that front-loads the identity modes before the payload and masking rules, so no sentence is wasted. The nested parenthetical describing the page URL versus /records/<slug> is harder to parse than necessary, and the return-field list could be itemized for faster scanning.

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 describing returns, and it covers the full payload, the masking behavior for unlisted/under-review records, and the error case. 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 100%, so the baseline is 3; the description earns more by adding the mutual-exclusivity constraint ('not both') and the provenance of the id value, neither of which appears in the schema where both parameters are optional with no oneOf restriction.

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 (returns) and resource (one business record) plus the two keying modes (id from search_records, or page slug for a listed record). It also enumerates the returned payload, so an agent can distinguish it from search_records and get_place 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 agent: ids come from search_records, slugs apply only to listed records, and 'Give id or slug, not both' sets the selection rule. It lacks an explicit when-not clause versus sibling lookups like get_place or get_entity, 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 cover readOnly, idempotent, non-destructive and closed-world, so the safety profile is done. The description adds genuinely new behavioral context: the response deliberately omits notes and contact data, and the unguessable id removes the need for an API key — an auth/capability-URL disclosure the annotations do not express.

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, front-loaded with purpose, then privacy scope, then auth rationale. Dense and mostly waste-free, though the 'by the id suggest_edit or suggest_place answered' clause is grammatically strained and costs a little 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 fully by naming the returned fields and explicitly stating what is excluded (note, contact data). For a single-id lookup with annotations carrying the safety profile, nothing needed 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?

With one parameter at 100% schema coverage the baseline is 3; the description goes further by explaining where the id originates (suggest_edit or suggest_place), that it is unguessable, and that no credential accompanies it. That is meaningfully more than the schema's 'The suggestion's id.'

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 ('Returns where one suggestion stands') and enumerates the payload shape: status, decision code, decision time. It also names the sibling tools (suggest_edit, suggest_place) whose returned id feeds this call, so an agent can distinguish this read-back tool from the write tools that create suggestions.

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 provenance clause 'by the id suggest_edit or suggest_place answered' tells the agent exactly when this tool applies: after a suggestion submission. There is no explicit when-not or named alternative for other lookup needs (e.g., get_record), so it falls just 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 already declare read-only, idempotent, closed-world; the description goes well beyond them by disclosing search radii (400 m, 800 m), the cap of three bus stops, nearest-first ordering, that meters and walking minutes accompany each entry, and that a sources field reports dataset provenance and last-checked time. For a tool with no output schema, this is exactly the behavioral context needed.

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 a single dense enumeration of returns that avoids repetition. It is one long run-on sentence, which slightly hurts scanability, but nearly every clause 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?

Without an output schema, the description fully specifies the return payload (per-category radii, ordering, provenance). The one gap is behavior for coordinates outside Milwaukee coverage or when a category has no results — the agent cannot tell whether it gets an empty list or an error.

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

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

Both parameters are fully described in the schema (100% coverage) with range bounds and example values, so the baseline is 3. The description only adds the implicit constraint that the coordinate should be a point in Milwaukee; it adds no format or validation detail beyond the schema.

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

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

States a concrete resource and scope: car-free access to a Milwaukee point, with bus stops, bike docks, EV chargers, parking meters, and public structures enumerated. No sibling (places_near, get_place, search_places) overlaps this multimodal-access resource, so an agent can route to it from the name and first clause 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?

The phrase 'without a car' and 'where to park or charge' implies when the tool fits, but there is no explicit when-not guidance and no named alternative for the nearby-places case (places_near, get_place). Usage must be inferred from the returned-data list.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the not-found contract ({"error": "not_found"}) and that replies are "live" and ordered, implying hidden or deleted content is filtered out. It stops short of saying whether reply lists are truncated or paginated.

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, verb-first, zero preamble. Every clause in the enumeration carries information (what fields come back, reply ordering, marked-answer presence), and the error case is confined to its own short sentence.

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

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

With no output schema, the description must carry the return shape and it largely does — including the error case. For a single-parameter read tool this is close to complete; only reply-count limits and per-reply metadata (author, timestamps) are left unstated.

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 slug's pattern and example are already documented in the schema, so the description only echoes the key without adding format or constraint detail. Baseline 3 applies where the schema does 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 ("Returns one topic by its slug") and then enumerates exactly what a topic is composed of: title, about, status, opening post, ordered live replies, and the marked answer. That enumeration is what separates it from list_topics (many) and open_topic, which an agent can see 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?

The single-slug framing implies it is the lookup path when the slug is already known, and the sibling list_topics supplies the obvious alternative, but the description never says so explicitly and lists no exclusions. Usage is inferable rather than 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: the data sources and the shape of each returned trend. With no output schema, disclosing result fields is valuable; missing only result counts/limits or freshness details.

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 compact sentences, front-loaded with geography and time window, followed by return content and then usage. Minor redundancy between "what is trending... today and this week" and "what people... are talking about now," but no sentence 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 single-optional-parameter read tool with no output schema, the description supplies both the return-field inventory and the source provenance, which is what an agent needs to decide to call it and to trust the results. Volume limits and recency semantics remain unspecified.

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 single neighborhood parameter is fully documented in the schema, including slug format and an example. The description only restates that narrowing is optional, adding no syntax or semantics 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 and resource with explicit scope: trending content in Milwaukee County over today and this week, sourced from local independent news and venues. The content profile (title, cited sentence, source links, linked places/events/neighborhoods) makes it clearly distinct from sibling lookups like get_entity, get_place, or search.

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 it for what people in Milwaukee are talking about now" gives a clear situational cue, and the closing line states the optional narrowing behavior. It does not name an alternative tool or state when-not to use it, 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 already cover readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: results are live, comments are anonymized ('No names'), and an unknown page yields { "error": "not_found" }. It stops short of describing ordering, limits, or what 'live' means operationally.

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: payload first, then the anonymization rule, then the error contract. Dense and front-loaded, with only minor compression possible in the comments-labeling clause.

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 return-value burden and does so well (counts, score range, comment format, error sentinel). It leaves open whether comments are truncated or ordered, which matters for a collection-like 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% and the single 'page' parameter is already documented as a URL/path/slug. The description restates 'place or record page' without adding format or validation detail beyond the schema, so it sits at the baseline.

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 ('Returns the live visit reports') and then enumerates the payload: counts, a 0-1 score, and labeled comments. An agent can distinguish this from submit_visit_report or get_place purely from the description 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?

Usage is implied by 'live visit reports of a place or record page' — read reports rather than write one — but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. get_place for the place itself, submit_visit_report for writing). The agent must infer the routing from sibling names.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds non-obvious semantics beyond that: deprecated categories and places are excluded, and unlisted places are not counted in the totals — a real caveat about what the counts mean. It does not mention response size or whether the taxonomy is paginated, which is the only remaining 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?

Two sentences, front-loaded with the resource and scope, followed by the filtering caveat and the downstream usage hint. The dense field enumeration in sentence one is doing real work rather than padding, and nothing repeats the annotations.

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 carries the full burden of describing returns — and it does, naming every field, the sort order, and the exclusion rules. For a zero-parameter read tool, 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?

The tool takes zero parameters, so per the baseline this lands at 4. The description instead spends its words on return-field semantics (slug, plural name, group, kind, counts), which is a reasonable substitution but is not parameter 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?

Opens with a specific verb and resource ('Lists the Little Milwaukee category taxonomy') and enumerates exactly what each entry contains: slug, name, plural name, group, kind, description, place count, subcategories, plus the sort order. An agent can distinguish this from sibling enumerators like list_tags and list_topics 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?

The final sentence gives a concrete downstream directive: 'Use a slug as the category filter of search_places or places_near,' which tells the agent why to call this and what to do with the result. It stops short of naming when NOT to call it or how it relates to list_tags/list_topics, so it falls just short of the top band.

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 read-only, idempotent, closed-world behavior. The description adds useful behavioral detail beyond them: deprecated and unlisted places are excluded from counts, and results follow vocabulary-page order.

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 the core action and return contents first, followed by counting behavior and then downstream usage. Every sentence carries useful information without repetition.

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

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

With no input parameters and no output schema, the description adequately explains what is returned: each tag's definition, place count, slug-based downstream use, ordering, and count exclusions. 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?

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description appropriately focuses on return contents and downstream filter usage instead.

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: it lists the curated tag vocabulary. It also names example tags, return contents, and ordering, making the tool clearly distinct from generic category/topic listers.

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 downstream usage: use the returned slugs as the tags filter for search_places or places_near. It does not explicitly say when to prefer list_categories or list_topics instead, so it falls just short of full 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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description still earns credit for two non-obvious traits: results are public-only and ordered newest-activity-first, which shapes how the agent should read the output. Pagination, page size and totals are not disclosed, keeping it below 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?

Verb and resource lead the sentence and the ordering constraint follows immediately. The second half drifts into platform framing ("the place to ask the community…") that is more about the forum than about calling this tool, so it is not fully waste-free.

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 two-optional-parameter read-only list tool with full annotation coverage and no output schema, the description covers purpose, scope, ordering and filters. It stops short on result volume/pagination, which matters for a newest-first feed an agent may need to page through.

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 descriptions for about and status are already detailed (URL, path, bundle path; enum values). The description only restates "filter by the page a topic is about and by status" without adding format guidance or default behavior, so the schema is doing 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?

"Lists public discussions (Topics) on Little Milwaukee, newest activity first" gives a specific verb, resource, scope and ordering, which cleanly separates it from the singular sibling get_topic. The agent knows immediately this is the collection browse endpoint.

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 phrase "read what people and agents found out" implies browsing, but the description never states when to use this versus get_topic (single topic), search (query-driven) or open_topic (posting). Worse, "the place to ask the community" describes the community's activity rather than this tool's, so an agent skimming could mis-attribute posting to a read-only list 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?

Goes well past the annotations: rate limit of 20 posts/hour per key, automatic moderation that can hold or flag the post, the 401 behavior for an invalid key, and a concrete redaction contract (emails/phones/addresses stripped, external links rewritten to '[link removed]'). It also discloses the body length that triggers a hold — behavior the schema's maxLength does not 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?

Purpose is front-loaded in the first clause, but the rest is a single dense sentence chain with nested parentheticals about rate limits, moderation, and redaction. Everything is relevant, yet the packing makes it harder to skim than a short bulleted breakdown would be.

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 public, open-world write with no output schema, it covers auth, moderation, redaction, limits, and the failure mode well. The remaining gap is the return value — no output schema exists and the description never says what comes back (post id, URL, or pending state), which an agent needs to confirm success.

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; the description adds meaning beyond it by tying the 2000-character hold to body and by explaining that links to littlemilwaukee.com and the pages it cites survive redaction, which clarifies what belongs in 'about'. It still doesn't explain the agent-vs-key interaction on the 'agent' parameter beyond the schema's own note.

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 — opening a public topic to ask the community — and the required title/body plus the unverified-visitor attribution make the create-new-post intent clear against get_topic/list_topics. The word 'open' is slightly ambiguous (could read as 'open an existing topic'), but the surrounding text resolves it.

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 real usage condition: send a bearer key for a live post, omit it and the topic is held for mayor/editor approval, plus an explicit consent directive ('Ask before posting for your person'). It never routes to siblings like reply or deputy_draft, so an agent must infer that responding to an existing topic is a different 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 only cover the safety profile (read-only, idempotent, closed-world), and the description goes well beyond that: deprecated and unlisted places are excluded, drafts are returned with status "draft", results are capped at 50 and sorted nearest-first, distances are straight-line meters, nearest_stop is limited to 400 m and may be null, and an out-of-vocabulary tag returns {"error": "invalid_input"}. Those are exactly the behavioral traits an agent needs and cannot get from 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?

The core purpose is front-loaded in the first clause, which is good, but the remainder is a long run-on chain of coordinated clauses mixing filtering rules, response-field documentation and error behavior. Every clause carries information, yet the density and lack of separation make it harder to scan than it needs to be.

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 shape — and it does: distance in meters, canonical page URL, nearest_neighborhood, nearest_stop with routes and nearest_stop_source feed dates, plus the error envelope. Combined with the annotations and the fully described schema, an agent has everything needed to call this 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 description coverage is 100%, so lat, lng, kind, tags, category and radius_m are already documented (including the anyOf list/CSV form for tags and the 1500 m default with 10000 m cap). The description adds little parameter-level meaning beyond restating the AND semantics of tags and the existence of a tag vocabulary, which the schema already implies via 'every one of these tag slugs'. 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 ('Lists locally owned places') plus the geographic predicate (within a radius of a lat/lng), the ordering ('nearest first') and the cap ('at most 50'). That scope — radius around a point in Milwaukee County — is clearly distinguishable from the text-query sibling search_places 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?

Usage is implied by the geometry ('within a radius of a latitude and longitude'), so an agent can infer this is the proximity-search tool rather than the text search. However, no sibling is named and there is no explicit when-not guidance (e.g. that search_places should be used for keyword lookups or get_place for a known slug), so the agent must infer the 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?

Goes well beyond the annotations: 20 replies/hour per key, automatic moderation, unauthenticated replies held for a mayor or editor, 4000-char cap with a 2000-char moderation threshold, PII stripping of emails/phones/addresses, and a 401 for invalid keys. The annotations only say it is a non-idempotent, open-world write; the description supplies all the operational consequences.

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 and every sentence carries load-bearing information (rate limit, moderation, size cap, PII, error code) with no filler. The middle sentence is long and packs several constraints into one breath, slightly hurting 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?

For a write tool with no output schema, it covers auth, rate limits, moderation outcomes, size limits and failure codes thoroughly. The only gap is what a successful call returns (confirmation, reply ID, or held-state indicator), which the agent cannot infer.

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 real meaning: the 2000-character moderation threshold is not in the schema, and the attribution behavior for the optional `agent` field is explained contextually. It still doesn't explain the slug pattern or how to obtain one beyond the schema's own note.

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 opens with a specific verb and resource ("Replies to an open topic") and immediately clarifies the attribution model ("a visitor, through their agent"), which separates it from open_topic and the deputy_* drafting tools. It never names a sibling explicitly, so the differentiation is inferred from the verb rather than stated.

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 guidance on what belongs here ("a good place to leave what your person found out") with a worked example, plus the conditional branch for authenticated vs. unauthenticated use. It stops short of naming an alternative tool when a reply is the wrong fit (e.g., submit_visit_report for structured reports).

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 past the readOnly/idempotent annotations by disclosing result ordering ("best first"), the per-result fields (kind, url, status, score, match_reason), and the meaningful caveat that drafts are unreviewed and records are not editorial listings. It does not restate the schema's result-cap behavior (limit > 50 returns 50) or any rate limits, so it stops short of fully self-contained.

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 and the routing instruction, and almost every clause carries information. It is a dense, somewhat run-on paragraph with several example strings that could be trimmed, which keeps it from a 5.

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 and 8 parameters, the description compensates by describing the shape of returned results and their ordering, plus the review status of drafts versus records. Combined with 100% schema coverage, 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantic value: it explains that known words are implicitly converted into filters (category names and plurals, neighborhood names, tags, "open now", "mayor") and that parse=false disables that. This tells the agent how to phrase a query rather than how to fill a field, which the schema 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?

Opens with a specific verb and an explicit enumeration of the corpora searched: listed places, City of Milwaukee business license records, neighborhoods, categories, collections and Mayor roles. That enumeration also distinguishes it from search_places and search_records, so an agent can tell which tool covers which corpus without opening schemas.

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 "use it first for any lookup by name, street, phone fragment, license type or topic" and backs that with worked example queries. It also names the alternative and the condition that selects it: meaning-only questions about places should go to search_places, which ranks by embeddings 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?

Goes well beyond the annotations: result ordering (closest to furthest match), inclusion of canonical page URLs, exclusion of deprecated and unlisted places, drafts surfaced with status 'draft', graceful fallback to name/text search under budget exhaustion, and the exact error shape for an out-of-vocabulary tag. That is a lot of behavior an agent could not otherwise predict.

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 purpose and examples, then layers filtering, result shape, freshness rules, fallback, and error behavior in a tight sequence. Six sentences and each one carries distinct, non-redundant 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?

With no output schema, the description still covers the return format (ordered results with canonical URLs), inclusion rules, degraded-mode behavior, and the error contract. An agent has everything needed to call this correctly and interpret the failure case.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: tags are AND-matched ('every tag must match'), and an invalid tag yields { "error": "invalid_input" }. It also points at list_tags and list_categories for vocabulary, which the schema only hints at for tags.

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 (searches), resource (locally owned places), geographic scope (Milwaukee County), and mode (by meaning), backed by two concrete query examples. This differentiates it clearly from sibling tools like get_place, places_near, and search_records.

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 examples ('friday fish fry with perch', 'frozen custard on the south side') make the intended semantic-search usage clear, and the description explains the degradation path when the embedding budget is exhausted. It stops short of explicitly naming when to prefer places_near or plain search over this tool, so the choice is inferable rather than 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?

Beyond the read-only and idempotent annotations, the description discloses important behavior: fuzzy name matching, ranking rules, neighborhood boundary filtering, citation URL rules, and privacy constraints for unlisted or under-review records. It adds substantial operational context without contradicting 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?

The description is front-loaded with the core purpose and remains information-dense throughout. It is somewhat long as a single paragraph, but nearly every sentence carries useful scope, ranking, citation, or privacy 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?

With no output schema, the description supplies the return context an agent needs: facts and sources, methods and check dates, page URLs for citation, and what is suppressed for unlisted or under-review records. That is complete for a read-only search tool with well-documented parameters.

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 in detail. The description reinforces the query matching semantics and some filter behavior, but it does not add much parameter-level detail beyond what the input schema provides.

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

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

The description states a specific verb and resource: it searches Milwaukee business records by name, including both listed and unlisted records. It clearly scopes the data to city license and property sources and explains the matching basis, which makes the tool distinguishable from a generic place search or record fetch.

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 a clear usage context by explaining name-similarity matching, ranking behavior, and filterable dimensions. It does not explicitly name alternatives such as search_places or search and does not state when not to use this tool, so it falls short of full 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.

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

Annotations only declare the write is non-destructive, non-idempotent, and open-world. The description adds what the annotations cannot: submission triggers a machine quote-vs-page comparison followed by a human read, and nothing publishes automatically. It also discloses auth requirements (Bearer agent key) and the failure shape (invalid_input with remediation guidance).

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?

Five short sentences, front-loaded with the action and immediately followed by the prerequisite, with no filler. The first sentence is slightly overloaded by packing audience, scope, and sourcing into one clause, but nothing 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 an 11-parameter mutation with no output schema and full schema coverage, the description covers auth, prerequisite ordering, review pipeline, and error behavior. The remaining gap is what a successful call returns or what happens to the submission afterward (queued status, identifier), which an agent might want.

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 still adds real meaning: "Never invent a fact" and "researched from the organizer's own page" constrain what source_url and quote may contain, beyond the schema's format rules. It does not, however, add field-level guidance to the seven required parameters.

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 gives a specific verb and resource ("Sends a public event"), the geographic scope (Milwaukee County), and the sourcing constraint (researched from the organizer's own page). That combination cleanly separates it from siblings like submit_page, submit_verification, and suggest_edit, which handle different record types.

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 the gating condition ("for an agent whose person said yes"), an explicit ordering prerequisite ("Call check_duplicate first"), and a fallback path for missing credentials (the /contribute URL). When-not-to-use is covered implicitly by the duplicate check and by the rule against naming a private person.

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: it discloses the downstream pipeline (failed check returns invalid_input with what to fix; a passing draft goes to a judge and then to a person), that nothing is listed automatically, and that the submission is attributed to the agent. It also states the Authorization: Bearer <agent key> requirement and that the rate limit depends on agent level. It does not address retry/idempotency behavior despite idempotentHint=false, which leaves the biggest behavioral gap for a write 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?

Front-loads the action and the precondition, then moves through constraints, failure behavior, auth, and limits in a logical order. Slightly run-on, with several distinct rules packed into a single paragraph, but 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 a non-idempotent write tool with no output schema, the description covers the important unknowns: the validation behavior and error code, the review pipeline, the fact that nothing publishes automatically, and the auth mechanism. What a successful call returns (a draft id or status handle for get_page_status) and how duplicate resubmission is treated are left unstated.

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 and the schema already carries the detailed rules for body length, citation format, and source quotes. The description reinforces the grounding constraint ('never invent a fact') but adds no syntax or format meaning beyond what the schema documents, including the origin hints for record_id and category.

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: 'Sends a whole page draft for a business record.' That is more specific than the bare name and makes clear the artifact is a full page draft rather than an edit or a note, which separates it from siblings like suggest_edit and deputy_note. It never names a sibling outright, so the differentiation is inferential 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?

Supplies a real precondition — 'for an agent whose person said yes' — and implies the tool is for submitting finished drafts, but never says when to prefer this over submit_verification, suggest_edit, or deputy_draft. The agent must infer the boundary from the phrase 'whole page draft' 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?

Goes well beyond the annotations by disclosing side effects: a confirmation is stored for human review and does not change the fact or its check date, while a dispute additionally opens a suggestion. It also surfaces the auth requirement (Authorization: Bearer <agent key>) that annotations do not express. The only gap is retry/idempotency behavior, which matters given idempotentHint=false, but the mutation semantics are unusually well explained.

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 confirm/dispute rule before secondary details like storage effects and auth. The telegraphic phrasing ("Website, phone and hours only.") is efficient, though the run of short declaratives makes it slightly disjointed to read.

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 6-parameter mutation tool with no output schema, the description covers the important ground: decision rule, prerequisites, side effects, scope limits and auth fallback. What is missing is what the call returns on success and whether resubmitting the same task is safe, which an agent retrying a failed call would want to know.

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 defines task_id, result, source_url, quote, date_verified and note. The description reinforces the quote and source_url requirements and restates the confirm/dispute semantics, but adds nothing about date_verified or the conditional note field beyond what the schema says. Baseline 3 is appropriate when the schema carries the load.

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 and resource ("Answers a verify task from get_open_work") and names the sibling tool that produces the input, so the agent can distinguish it from suggest/suggest_edit/deputy_note without opening any schema. The scope line ("Website, phone and hours only") further pins down what kind of task it accepts.

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 decision criteria for the enum: confirm when the source states the fact as shown, dispute when it states something else. It also states the prerequisite source material (a URL and copied words), the domain restriction, and a concrete fallback path when no API key is available.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds substantial behavioral context: Bearer authentication is required, one report per person per page every 90 days, automatic moderation can hold it for a mayor or editor, and reports from unclaimed agents are held and count for nothing. These are material facts an agent needs before calling.

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 dense but front-loaded: the core action comes first, followed by consent instructions, auth, and rate/claim caveats. Every sentence carries operational weight, though the consent paragraph is lengthy and could be tightened without losing meaning.

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, nested-object write tool with no output schema, the description covers authentication, consent, rate limiting, moderation, and unclaimed-agent behavior thoroughly. It does not describe the return value, but the absence of an output schema makes that a minor gap against otherwise strong coverage.

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 structured schema already defines all parameters, including the context enum and consent.wording. The description reinforces a few semantics (the 500-character limit, the context list, the consent.wording requirement) but does not add significant syntax or format detail 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?

The description opens with a specific verb and resource: 'Publishes your person's first-hand report on a place or record page,' then enumerates the content shape (visited, recommend for context, words). An agent can distinguish this write operation from sibling reads like get_visit_reports 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?

It gives explicit prerequisites: 'Ask first,' consent must be obtained, and the exact consent flow with consent.wording is described. It also sets the 90-day rate limit and notes automatic moderation can hold the report. It stops short of naming alternative siblings, but the write-vs-read distinction from siblings like get_visit_reports is implicit in the verb 'Publishes.'

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 safety profile (readOnly, idempotent, non-destructive, no open-world), so the description spends its budget on what annotations can't convey: matching semantics (prefix, or word-prefix for business records), a hard cap of 8 results, ordering ("best first"), and the payload of each suggestion (page URL plus photo/logo when present). It does not cover degenerate cases such as zero matches or partial-match fallbacks, which keeps it below 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?

Two sentences, front-loaded with the core behavior and closed with the sibling routing advice. The entity-type enumeration is long but functional; every remaining clause carries result-shape information the agent cannot get elsewhere.

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

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

With only two parameters, no output schema, and annotations already declaring the read-only profile, the description supplies the missing pieces: result cardinality, ordering, and per-suggestion fields. An agent has everything needed to call it and interpret what comes back.

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 earns above that by explaining what q actually matches against (name prefixes and word-initial matches for business records), semantics the schema's "text typed so far" phrasing only loosely implies. The limit cap of 8 is restated from the schema, adding no new value.

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 – completing a partial name as a person types – and enumerates the entity classes it covers (places, neighborhoods, categories, collections, roles, business records). This is clearly a typeahead tool, distinguishable from the sibling 'search' without inspecting 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 sets the use case ("as the person types" – prefix autocomplete) and names the alternative: "For a full ranked search with filters, call search." The routing condition between the two tools 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?

The description adds substantial behavioral context beyond the annotations: it explains the automatic judge, which identities can get small changes auto-confirmed, that agent-submitted suggestions wait for a mayor or editor, the same_as_current response case, and the status_url returned for the decision. It also clarifies that source_url is for human verification and is not counted as a source by the judge.

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 and then supplies dense but relevant details about elements, fields, and workflow. It is long and lacks paragraph breaks, but the length is largely justified by the tool's complexity and the variety of editable elements.

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 mutation-suggestion tool with no output schema, the description covers the core workflow, approval behavior, and response hints such as status_url and ok false. The main gap is that collection-specific elements are not enumerated even though collections are listed as a page type.

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?

Although schema description coverage is already 100%, the description adds rich meaning by enumerating valid element IDs for places, neighborhoods, categories, links, tags, and photos. It also explains special forms such as same_as-<n>, tag-new, photo-<n>, empty-value removal, address fields, and hours formatting.

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: suggesting a change to one element of a Little Milwaukee page. It names the page types and element scope clearly, but it does not explicitly differentiate itself from siblings such as suggest or suggest_place.

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

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

The description explains how to identify the page and element, and it details the approval path, which gives useful context for use. However, it does not explicitly say when to use this tool versus sibling tools like suggest_place, so the routing guidance is implied rather than 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?

Goes well beyond the annotations by disclosing the full lifecycle: nothing is published by this call, a mayor or the editor drafts the page only if it meets the inclusion rule, and the response carries a status_url for the decision. It also pre-declares the duplicate failure shape, which annotations cannot express.

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 inclusion rule, then flows into inputs, lifecycle, and failure mode. The closing fragment about status_url is slightly tacked on but still earns its place as return-shape 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?

With no output schema, the description steps in to sketch the return: ok/reason/existing_url and status_url. Submission acceptance criteria and the draft-approval flow are covered; only the success-path details and optional fields are left 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?

Names the six required inputs and tells the agent where category slugs come from (list_categories), which the schema does not. However, it is silent on all six optional fields, including source_url which the schema itself marks "strongly preferred" – a notable omission at 75% coverage.

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 ("suggests a new place") and qualifies it with concrete inclusion criteria (locally owned, Milwaukee County, wouldn't make sense elsewhere). An agent can distinguish it from suggest_edit, which is explicitly named as the path for places the site already holds.

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 this is the wrong call: a duplicate answers ok false with existing_url, and the agent should pivot to suggesting edits or claiming the business instead. Strong conditional routing, though it never contrasts with the plain `suggest` and `suggest_edit` siblings up front.

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 the annotations: re-voting the same way removes the vote, the other answer changes it, the vote only counts from a verified agent at a counted trust level, votes never publish as fact, and an Authorization Bearer key is required. This clarifies the non-idempotent, non-destructive write semantics that annotations alone leave ambiguous.

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: what is recorded, how repeat votes behave, then the trust/auth caveat. Scope and action are front-loaded 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?

No output schema exists, yet the description covers the mutation semantics, auth requirement and the counted/uncounted outcome. The only mild gap is not spelling out the response shape beyond the implied counted flag.

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 earns a bump by narrowing which records are valid (not a listed place) and framing person_hash as 'your person's answer', linking it to the submit_visit_report identity concept.

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 (records a vote), a specific resource (a business record that is not a listed place), and the exact answer domain (local / not_local). The scope restriction to non-listed-place records cleanly separates it from place-oriented 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?

Clearly says when this tool applies (a business record that is not a listed place) and what the two answer values mean. It does not name a sibling to use instead for listed places, so it stops just short of explicit alternative routing.

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