覓安居

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

With no annotations present, the description carries the full burden. It does disclose two valuable traits: the action is destructive and it only affects the caller's own note, plus the auth requirement. It says nothing about whether deletion is reversible, whether a missing note errors or is a no-op, or what the response looks like.

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?

One sentence, front-loaded with the action and scope, with the auth prerequisite in parentheses. Nothing is redundant, though the terseness comes at the cost of omitting behavioral detail.

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

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

The tool is simple (one required param, no output schema, no annotations), so a short description is defensible. Still, for a destructive operation with zero annotation coverage, the absence of outcome and failure-mode information leaves a noticeable gap.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines facility_id as 機構編號. The description only reiterates that the note belongs to the specified facility, adding no syntax, format, or sourcing detail beyond the schema.

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

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

The description states a specific verb (刪除) and resource (筆記) and narrows scope to the current logged-in user's note for a specified facility (目前登入者對指定機構). That scoping distinguishes it from sibling note tools such as get_note and upsert_note without naming them.

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

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

The only guidance is the prerequisite that an Authorization Bearer token is required. There is no statement of when to prefer this over alternatives (e.g. upsert_note with empty content), nor any note about idempotency or what happens when no note exists.

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

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

With no annotations, the description carries the behavioral burden and does it well: it discloses the auth requirement (Authorization Bearer/OAuth) and the null fallback when no user is present. It does not mention error behavior on an invalid or expired token, which is the main remaining gap for an auth-dependent read.

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 sentence, front-loaded with the return value, followed by the auth prerequisite and null case. Every clause earns its place and there is no redundant restatement of the tool name.

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 describe returns, and it does: name, email, and null when absent, plus the auth requirement. For a zero-parameter read this is nearly complete; only error/expired-token behavior is 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?

The tool takes no parameters, so the baseline is 4. The description adds no parameter detail because there is none to add, and none is needed.

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

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

States a specific verb and resource (returns the current logged-in user's name and email), which is clearly distinct from the sibling tools that deal with facilities, notes, and city/district counts. The only reason it isn't a 5 is that 'profile' is enumerated only in terms of two fields, leaving open whether other profile data exists that isn't returned.

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: an agent can infer it should call this to identify the current user. There is no explicit statement about when to use it, when not to use it, or what to do if the caller is unauthenticated beyond the null return.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a real payload trait — roster fields included, sources/note/person_in_charge excluded — which is valuable, but it says nothing about read-only nature, not-found behavior, permissions, or response envelope.

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?

One compact sentence, front-loaded with the verb and resource, with inclusions/exclusions condensed into a parenthetical. Slightly dense but no wasted wording.

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

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

For a one-parameter read tool with no output schema, the description covers what comes back at the field-group level (roster included, three fields excluded), which is the main ambiguity an agent would have. Remaining gaps — error/not-found behavior — are minor at this complexity.

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?

Single parameter with 100% schema description coverage, so the baseline is 3. The description restates 'by facility id' but adds no format, prefix, or sourcing guidance beyond the schema's '機構編號'.

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

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

States a specific verb+resource: retrieve a single facility's details by facility id. The 'single, by id' framing inherently separates it from the list_* and search_facilities siblings, though it never names them explicitly.

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

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

Usage is only implied: 'by id' signals this is for when the caller already has an id, versus search_facilities for discovery. No explicit when-to-use, when-not-to-use, or named alternative 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?

With no annotations, the description carries the full burden and does disclose two useful behaviors: the Authorization Bearer requirement and that the result is null when no note exists. It omits read-only framing, error/permission-failure behavior, and any rate-limit or pagination context.

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

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

A single compact sentence with the subject (current user's note), the scope (specified facility), and the null case plus auth note all front-loaded; nothing is wasted.

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

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

For a one-parameter read with no output schema, the description covers what is returned, the empty-result case, and the auth prerequisite. Only sibling routing (list_notes/get_facility) is missing, which is a modest gap.

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

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

Only one parameter and schema coverage is 100%, so the schema already defines facility_id as 機構編號. The description confirms the ID scopes the lookup to a single facility, but adds no format or validation detail beyond the schema — correct baseline 3.

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

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

States a specific verb+resource+scope: 讀取 (read) the current logged-in user's 筆記 (note) for a specified 機構 (facility). This is clearly narrower than list_notes or upsert_note, though it never names those siblings explicitly.

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

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

Usage is implied by '對指定機構' — call it when you need one user's note tied to a single facility. There is no explicit when-not guidance and no pointer to list_notes for enumerating multiple notes, so the agent must infer the boundary.

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

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

With no annotations present, the description carries the full behavioral burden and does disclose two meaningful traits: the result set is a complete fixed enumeration of 22 administrative units, and cities with no institutions are explicitly returned as 0 rather than omitted. It omits ordering, but for a zero-parameter read of a small fixed dataset that gap 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?

A single sentence with no filler, front-loading the scope (22 縣市) and the key caveat (zero-filled for empty units). Nothing is wasted.

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

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

There is no output schema, so the description has to describe the return values, and it does: 22 city/county entries plus counts with explicit zero-filling. Only ordering and the exact field format remain unspecified, which is minor for a small fixed payload.

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 the baseline is 4 and there is no parameter meaning left to add; the description correctly allocates its words to the return shape 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 (回傳) paired with a precisely scoped resource (the 22 縣市 and their 機構數), so an agent knows exactly what it will get back. It does not distinguish itself from the sibling list_district_counts, which offers an apparently similar aggregation at a different granularity, leaving that differentiation to the caller's inference.

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

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

There is no when-to-use guidance, no prerequisites stated, and no mention of the obviously related list_district_counts alternative. The agent must guess whether city-level or district-level counts are wanted.

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?

No annotations are supplied, so the description carries the full burden. '回傳' implies a read-only query, but the description says nothing about the return shape (district name paired with a count), ordering, behavior for an unknown or empty city, or pagination. For a data-returning tool with no output schema, this leaves significant behavioral gaps.

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 short sentence with no filler, and the resource ('行政區與機構數') is front-loaded immediately after the verb. It is efficient, though its brevity borders on under-specification rather than tight polish.

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 (one required string parameter, no nesting, no output schema), and the description conveys the core return concept of districts plus counts. However, without an output schema the description should say more about the result structure and edge cases, and it offers no routing guidance against the related count/list siblings.

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 is one parameter and schema description coverage is 100%, with the schema itself supplying an example value (「臺中市」). The description only restates the parameter as '指定縣市' and adds no format, matching, or normalization details beyond what the schema already 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 states a specific verb and resource: it returns the administrative districts and their facility counts for a given county/city, scoped by the required 'city' parameter. An agent can understand what it produces without opening the schema. It does not, however, differentiate itself from the sibling list_city_counts, which likely returns a similar aggregate at a different level.

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 explicit when-to-use guidance, no mention of alternatives such as list_city_counts, and no prerequisites or exclusions. The required 'city' parameter implies the tool is used for a single-city breakdown, but that inference is left entirely to the agent.

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

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

With no annotations present, the description carries the full behavioral burden. It usefully discloses the authentication requirement (Authorization Bearer), which is real context an agent needs, but it omits pagination behavior, result-size expectations, and whether the listing is read-only or sorted in a particular way.

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 short sentence with zero filler, front-loading the action and the scope before the parenthetical auth note. Every element earns its place.

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

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

For a zero-parameter read-only listing tool with no output schema, the description covers what the tool returns at a conceptual level and flags the auth prerequisite. The remaining gap is minor: no mention of pagination or ordering, but nothing blocks a correct invocation.

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 input schema defines zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless tool applies, and the description correctly implies no arguments are needed.

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

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

The description states a specific verb (列出), a specific resource (私人筆記), and the scope restriction (目前登入者), which lets an agent distinguish it from the single-note sibling get_note. It does not explicitly name an alternative or clarify how it relates to catalog-wide listing siblings, so it falls 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?

Usage is implied by the phrase 'currently logged-in user's private notes', which tells the agent this is a self-scoped read rather than a lookup by id. However, there is no explicit when-to-use versus when-not-to-use guidance and no named alternative for fetching a single note or notes belonging to other users.

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

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

With no annotations, the description carries the full burden. It usefully discloses the 12-result page limit and that results are returned as card fields, but it does not explain sorting, total counts, behavior with no criteria, or what exactly the card fields contain.

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

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

The description is two short sentences, front-loaded with the search purpose, followed immediately by pagination and return-shape information. There is no wasted wording.

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

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

For a simple four-parameter search tool, the definition covers the purpose, search facets, page size, and return format at a high level. However, with no annotations and no output schema, it leaves open how criteria combine, how empty searches behave, and what 'card fields' means, so it is adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents q, city, district, and page. The description maps the search criteria to those parameters but adds no syntax, format, or combination semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: search long-term care facilities by city, district, or name. This is clear enough to distinguish it in practice from detail-oriented siblings like get_facility, but it does not explicitly differentiate itself from them.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, and it does not mention alternatives such as get_facility for details or list_city_counts/list_district_counts for counts. The search criteria imply a use case, but that is not the same as 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?

No annotations are provided, so the description must carry the full behavioral burden, and it does disclose meaningful traits: an auth requirement (Authorization Bearer), a hard body size ceiling (2000 chars), the allowed status values, and that the operation is scoped to the current logged-in user. Gaps remain: it does not say whether an existing note's body is replaced or merged on update, nor what the response contains after the write.

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

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

Two compact sentences with the purpose and auth requirement front-loaded, followed by the two constraints that matter to the caller. Nothing is redundant with the schema beyond a harmless re-listing of status values.

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

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

For a three-parameter mutation with no annotations and no output schema, the definition covers the essentials an agent needs: what it writes, who it writes for, auth needs, size limit, and valid status values. It is not fully complete because it omits update/overwrite semantics and any indication of the post-write result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema omits: the 2000-character maximum on body (the schema has no maxLength). It also enumerates the status values, which the schema already lists, so the net gain is the size limit plus confirmation of the empty/omitted sentinel 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?

The description states a specific verb and resource ('新增或更新……筆記', i.e. create-or-update a note) scoped to the current logged-in user and a target facility, which distinguishes it from siblings like get_note, delete_note, and list_notes by its write semantics. It stops short of naming a sibling explicitly, so it lands at a clear 4 rather than 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 upsert framing implies when the tool applies (writing or amending a user's own note on a facility), and the Authorization Bearer requirement signals an authenticated write context. However, there is no explicit when-not guidance, no mention of how it relates to get_note or delete_note, and no stated prerequisite that the facility must already exist.

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