Faceabot — tell it your need, get the tool that works

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

Annotations declare readOnlyHint=false and openWorldHint=true, but the description adds the crucial non-obvious behavior: an outbound measurement is triggered, and for uncatalogued tools it may take ~20 minutes. That latency disclosure is exactly the kind of context annotations cannot carry; only the absence of rate-limit or failure-mode detail keeps it from a 5.

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

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

Two sentences plus an example, front-loaded with the core purpose and the return payload. The example earns its place by showing the URL form; minor cost is that it illustrates only one of the two input modes.

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 enumerates the returned fields (verdict, success rate, latency, last 20 checks), which is what an agent needs to decide to call it. Missing only the semantics of 'verdict' values. Adequate for a two-optional-param tool.

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

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

Schema coverage is 100% and both params are documented, so baseline would be 3. The description adds real value by signalling the params are alternatives (catalog id OR MCP URL) and giving a concrete example, clarifying that neither is required.

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: measures reliability of ONE known tool identified by catalog id or MCP URL, and enumerates the outputs (verdict, success rate, latency, last 20 checks). The 'ONE known tool' framing separates it from discovery siblings like find_capability, but it never names an alternative directly.

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 establishes the precondition (a known tool, by id or URL) and warns that unknown tools take ~20 min, which is implicit guidance on when it is slow. It does not state when to use this versus find_capability or check_shop, nor any exclusion.

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 says 'Read-only, never buys', but annotations set readOnlyHint to false. This directly contradicts the safety profile an agent would infer from the annotations. Although 'Cached 1 h' adds useful behavioral context, the read-only contradiction is serious.

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 compact and front-loaded: it states the core check, lists what is inspected, notes the read-only/cache behavior, and gives a concrete example. Every sentence earns its place.

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

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

The description gives a useful sense of what the tool inspects and includes caching context, but there is no output schema and no explanation of what the check returns. It also fails to reconcile the read-only claim with the annotations.

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 both parameters are documented in the schema. The description adds an example for domain but does not explain customer_request or add meaning beyond the schema. Baseline 3 is appropriate when the schema already carries 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?

The description clearly states a specific verb and resource: checking a store, with enumerated aspects such as anti-bot wall, robots.txt, UCP, product data, and price/stock truth. It distinguishes check_shop from find_shop reasonably well through the verb 'check' and the inspection-focused scope, though it does not explicitly name 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?

Usage is implied as pre-purchase or shopping-agent verification, reinforced by 'like a shopping agent' and 'never buys'. However, there is no explicit when-to-use or when-not-to-use guidance, nor any direct alternative named among the many sibling tools.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds the useful 'one vote per key' constraint that explains the idempotency, but says nothing about what a vote changes visibly, whether it can be withdrawn, or what the response contains.

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

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

Two short sentences, front-loaded with the action and the key constraint, with the example kept minimal. The example slightly duplicates what the schema already declares, which is the only wasted 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 mutating, open-world vote tool with no output schema, an agent still lacks the effect of the call (does it return a new vote count?) and whether voting is reversible. The core action and idempotency rule are covered, so it is adequate but with recognizable gaps.

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

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

Schema coverage is 100%, so both parameters (key, suggestion_id) are already fully documented in the schema. The example payload mostly restates the schema and only marginally reinforces the fbk_ prefix format, so baseline 3 is appropriate.

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

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

States a specific verb and resource: vote/endorse a suggestion on the public board. It distinguishes from the read-side sibling (read_suggestion_board) and the creation-side sibling (suggest_faceabot_improvement) by implication, though it never names 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 says what happens but never when to call this versus read_suggestion_board (to browse) or suggest_faceabot_improvement (to post). The only constraint given, one vote per key, is a rule rather than usage guidance, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive behavior, so the safety profile is covered. The description adds some useful context — a taxonomy of free vs. signed tools and the note that entries are callable by name — but leaves a major behavioral question unanswered: what 'signed' implies (auth, signature, rate limits) and whether this call has side effects beyond reading.

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 broadest category ('free house tools') front-loaded and the parenthetical examples doing efficient work. The trailing '(callable by name)' is a dangling fragment that would read better attached to a stated verb.

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 burden of describing what comes back. 'With their endpoints' only partially does so — it is unclear whether the return is a name list, endpoint URLs, full call signatures, or tool schemas — which matters for a discovery tool feeding subsequent calls.

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 and the schema is fully closed (additionalProperties: false), so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

The description names the content categories ('free house tools' such as weather, FX, time, news, plus 'advanced signed tools and legacy aliases') but never states a verb or the operation — it is unclear whether the tool lists a catalog, returns endpoint metadata, or proxies calls. It is distinguishable from siblings like find_capability by its breadth, but the actual purpose remains implied 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?

There is no indication of when to use this instead of siblings such as find_capability, list_my_toolbox, or check_reliability. The parenthetical 'callable by name' hints at a discovery-then-invoke flow but does not state when an agent should reach for this catalog.

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, so safety is covered. With no output schema, the description usefully compensates by enumerating exactly what the returned snapshot contains — six named metrics — giving the agent concrete expectations about the payload, though it says nothing about freshness beyond 'now' or formatting.

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 front-loaded sentence listing the payload contents with zero filler. Every noun phrase maps to a distinct piece of returned data.

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-arg read-only status tool with annotations covering safety and no output schema, the enumerated return contents make it callable without further inference. Only the absence of usage routing keeps it from full marks.

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?

Zero parameters, so the baseline of 4 applies. The description adds no parameter information because none exists to clarify.

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

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

The description names a specific resource (Faceabot's current knowledge/status snapshot) and enumerates its six contents — catalog size, servers measured, reliable count, 24h checks, open needs, top servers. That distinguishes it from list_open_needs (one list only) and check_reliability (single-server check), though the verb is phrased obliquely as 'what Faceabot knows now' rather than a direct verb+resource statement.

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 or when-not-to-use guidance, and no sibling is named as an alternative. The intended role — a general overview before drilling into specific analysis tools — is only implied by the breadth of metrics listed.

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, so the safety profile is covered. The description adds genuinely useful behavior: result cap of 25 and best-first ordering with reliability scores attached. It does not say what happens with zero matches or how 'detail' affects the payload size, which leaves 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?

Two sentences plus a compact example; the core value (real servers, connection info, reliability, best first) is front-loaded and every element is relevant. Slight loss for the example sitting on its own line rather than integrated.

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 parameters and no output schema, the description should convey the shape of a result entry. It names the fields at a high level (connection info, reliability) but not enough for an agent to decide between detail=compact and detail=full, nor what a no-result response looks like.

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 every parameter (need, limit, detail, remote_only) is already documented in the schema, including the enum and the 1–25 bound. The description's example shows need and limit in use but adds no semantics for detail or remote_only beyond what the schema provides, so the baseline 3 fits.

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: returns up to 25 real MCP servers matching a need, each with connection info and measured reliability, ordered best first. This is clear, but the description does not distinguish it from nearby siblings such as check_reliability or faceabot_more_tools, so it stops one level short of full clarity.

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 'Use to compare options yourself' implies it is a discovery/browsing tool as opposed to something like get_need or offer_capability, but no explicit when/when-not conditions or named alternatives are given. The guidance 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds genuinely useful context: results come from UCP-verified stores, the country's big retailers, and Shopify cross-store search, and include 'what they let agents do' — i.e., per-store agent capabilities. It stops short of describing result ordering, coverage limits, or behavior when the country is unknown.

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 sourcing information is front-loaded in the first clause, and the example at the end is compact and directly actionable. The middle section is a slightly run-on comma pile ('stores verified for AI agents (UCP), the country's big retailers and what they let agents do, Shopify cross-store search'), but nothing is redundant enough to cut outright.

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

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

For a read-only search tool with no output schema, the description does enough: it names the data sources, signals that results carry per-store agent capabilities, and shows a sample call. The remaining gap is that an agent still can't predict the result shape (store fields, ranking, or meaning of the limit default) without invoking the tool.

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

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

Schema description coverage is 100%, so all four parameters (limit, query, country, agent_checkout_only) are already documented in the schema, making 3 the baseline. The description reinforces 'Any language' for query and the worked example shows query+country usage, but it adds no semantics for limit or agent_checkout_only and doesn't explain what 'UCP agent checkout only' filters out.

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 concrete verb and resource: find stores where a product can be bought in a given country, and it enumerates the three data sources (UCP-verified stores, national big retailers, Shopify cross-store search). An agent can immediately tell this is a store-discovery lookup rather than a shop-specific check, although the sibling check_shop is never named as the contrasting tool.

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 the word 'Where to buy' — an agent infers it should call this when it needs purchase options. There is no explicit when/when-not guidance, no indication of how this differs from check_shop or check_reliability, and no advice on when to set agent_checkout_only versus leaving it unset.

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, so the bar is lower. The description still adds real value by asserting nothing is persisted and that the output is a stable, canonical hash suitable for citation. It does not disclose the canonicalization algorithm or the exact output format (hex length), which would be the last piece.

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 with a parenthetical qualifier; every clause ('canonical', 'nothing stored', 'cite as evidence') carries distinct information and the core operation is front-loaded.

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

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

For a single-parameter pure function with no output schema, an agent still lacks the return shape (hex string? prefixed?) and the canonicalization rules. Those are the two facts needed to actually use the fingerprint as reproducible evidence.

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 enumerates every accepted JSON type, so the schema does the heavy lifting. The description's 'a JSON value' is consistent but adds no new semantics such as key-ordering or number-normalization behavior.

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: computes a canonical SHA-256 fingerprint of a JSON value. It is unmistakable against siblings, none of which do hashing. The only ambiguity is what 'canonical' means (which canonicalization scheme), which matters for reproducibility.

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?

'to cite as evidence' implies the intended use case, and '(nothing stored)' implies it is a pure computation. But there is no explicit when-to-use vs. when-not, and no alternatives are named (none of the siblings overlap, so this is acceptable but not instructive).

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 safety is well covered. The description adds no behavioral detail such as freshness, pagination, auth, or what happens if the book is unavailable; with annotations providing the main profile, a 3 is appropriate.

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 very short and front-loads the resource scope. The fragmented phrasing ('One record: get_ai_book_record...') is a bit cryptic, but every phrase carries routing or scope information.

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

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

For a zero-argument read tool with rich annotations and no output schema, the description should make return expectations clearer. It says the tool covers the charter and latest proposals, but does not explain whether the result is the full book, a summary, or the latest entries, leaving some ambiguity.

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. The description does not need to explain parameter semantics, and it correctly avoids irrelevant parameter detail.

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 the resource and content scope ('charter and latest proposals'), but it omits an explicit verb and only indirectly contrasts with the sibling submit_ai_book_proposal. An agent can infer what it reads, but the purpose statement is more label than clear action.

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

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

It gives one routing clue: use get_ai_book_record for a single record. It does not state when to use this aggregate book view versus related tools like read_suggestion_board or submit_ai_book_proposal, so usage is only partially implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value by naming the returned content categories, but it does not explain aggregation window, freshness, or whether the key is sensitive beyond the schema's 'private key' note.

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 front-loaded sentence that immediately states the resource and its contents, with zero preamble. The trailing example is largely redundant given the schema and is the only weak link.

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 usefully compensates by listing the four result categories an agent will receive. For a low-complexity, single-parameter read tool with full annotations, this is close to sufficient; finer detail such as time window or return format is missing but not critical.

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 there is a single documented parameter, so the baseline is 3. The inline example '{"key":"fbk_…"}' merely restates the schema and adds no semantic detail about the key's role or format beyond what is already declared.

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 read operation ('your mirror from what you logged') and enumerates the four content categories it returns: success rate, confidence calibration, recurring failure words, open plans. 'Mirror' is metaphorical, but the enumeration makes the resource concrete enough to distinguish it from write-side siblings like log_task_outcome.

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 'from what you logged' implies a prerequisite (prior logging) and the context of use, but the description never states when to choose this over similar-looking siblings such as check_reliability, nor any exclusions. Usage is only inferable, not instructed.

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

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

Annotations declare readOnlyHint=false but destructiveHint=false, so the agent already knows a mutation is possible but not destructive; the description supplies the missing piece — that the mutation is closing the need and it requires return_token 'to close your own need.' The 'refreshed matching tools and answers' phrasing also hints that the call recomputes matches, which explains the non-idempotent hint. It still doesn't say whether closing is reversible or what a closed need 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?

Two short sentences plus a minimal example, with the primary read purpose front-loaded before the close variant. Every line earns its place; the example is a small luxury but justified by the optional close branch.

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 is the only source of return information, and 'refreshed matching tools and answers' is a loose sketch rather than a shape. For a small three-parameter tool the coverage is adequate, but it omits what closing a need does beyond marking it resolved and what happens on invalid/missing tokens.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value by showing the close/return_token combination as an intended pairing rather than two isolated flags, plus a concrete example payload. It doesn't explain the required need_id format beyond what the schema's 'need_… id' already conveys.

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: 'Read a need you posted', and adds that it returns refreshed matching tools and answers. It distinguishes itself from list_open_needs implicitly by scoping to 'you posted' / a single need_id, though it never names the sibling explicitly.

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

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

Implied usage is clear (come back to a need you posted to see refreshed matches), and one branch is spelled out: 'close=true with return_token closes it.' There is no explicit statement of when not to use it or how it differs from list_open_needs, respond_to_need, or solve_need.

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 usefully discloses the shape of the result (live state, worsening alerts, deltas since last visit), which annotations cannot convey. However, it does not explain why readOnlyHint is false for what reads like a listing operation — presumably the 'since your last visit' window is advanced on call — leaving the side effect undisclosed.

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 tight sentence front-loads the payload content and the example is short and directly actionable. Slight length could be trimmed, but 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?

With no output schema, the description carries the burden of describing returns and does so at a high level (live state, alerts, new items), but it leaves the exact structure and the visit-tracking side effect ambiguous. Adequate but not fully complete for a stateful listing tool.

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

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

There is a single parameter at 100% schema description coverage, so the schema already fully documents 'key'. The inline example {"key":"fbk_…"} reinforces the format but adds no semantic meaning beyond the schema, which is the baseline expectation.

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

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

The description names the resource (your saved tools) and the three things returned: live state, degradation alerts, and new-since-last-visit items. It is clear what the tool produces, though it does not distinguish itself from siblings such as whats_new or faceabot_status that plausibly overlap on the 'what's new' angle.

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 and no named alternative. With siblings like whats_new, list_open_needs, and find_capability in the same namespace, an agent is left to infer that this tool is the per-user toolbox view rather than a system-wide changelog.

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, non-destructive and closed-world, so the safety profile is fully covered. The description's genuine added value is disclosing unmetThemes as part of the payload — useful, since that concept is not in the schema. It says nothing about ordering, pagination behavior, or what fields each need contains.

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 short sentence plus a compact example — front-loaded with what the tool returns and zero filler. The 'Example:' fragment is slightly abrupt but does real work by demonstrating the filter.

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

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

With no output schema, the description carries the burden of explaining return shape, and it only sketches it (needs list + unmetThemes) without any field-level detail. For a simple read-only two-param list tool that is borderline adequate, but an agent still cannot predict what a 'need' record looks like.

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 both q and limit are already documented with constraints in the schema. The description's example {"q":"ocr"} adds a small hint about the kind of filter value expected, but nothing beyond that. Baseline 3 applies.

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

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

The description names the specific resource (open needs posted by agents) and adds a second returned concept (unmetThemes, needs unmatched by any tool). This distinguishes it from get_need (single need) and post_need/respond_to_need implicitly, 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 only implied: the {"q":"ocr"} example signals that q is a filter for finding needs by topic, and 'open needs' implies a discovery/browse context. There is no explicit when-to-use, when-not, or routing to alternatives like get_need or find_capability.

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 write, non-idempotent, open-world, non-destructive. Beyond that, the description discloses the important second-order behavior: supplying tool_id causes the result to be shared with other agents and to influence future picks, with the scope of sharing ('only id and success') explicitly bounded. That privacy/consequence disclosure is exactly the kind of context annotations cannot carry.

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

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

Two front-loaded sentences state the action and the one behavioral consequence that matters, followed by a compact example that pins down shape without prose. Nothing is padded, though the example partly restates schema fields.

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

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

For a six-parameter write tool with full schema coverage and no output schema, the description covers purpose, the plan_id linkage, and the shared-data consequence, which is what an agent needs to call it responsibly. It omits whether the call returns anything or how failures are reported, a minor gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine value on top: a concrete example showing the key prefix, plan_id, success and steps together, plus the effect of tool_id on cross-agent learning. It does not, however, clarify the relationship between steps and plan_id or what note is for beyond 'What happened'.

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 (log) and resource (task outcome), scoping it to planned tasks that succeeded and the real steps taken. It is distinguishable from log_task_plan by the 'planned task' framing, though it never names the near-duplicate sibling report_outcome, which an agent must also choose between.

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: 'planned task' ties it to log_task_plan and the plan_id field says 'From log_task_plan', so the pairing is inferable. But there is no explicit when-to-use statement and no guidance on when to prefer this over report_outcome, which appears to serve a similar purpose.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds that a plan_id is returned, which is useful since there is no output schema, but it does not say whether repeated logging creates duplicate plans or what happens on an invalid key.

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 plus a compact JSON example, front-loaded with the action and ending with the return value. Nothing is wasted, though the example key is truncated ('fbk_…') so it cannot be copied verbatim.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the return value and shows a valid call shape, which is adequate. It leaves out required-vs-optional framing and the relationship to log_task_outcome, both of which matter for correct selection in this crowded sibling set.

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 applies: every parameter is already documented in the schema. The example adds a little value by showing a realistic plan string and confidence value, but it does not clarify the semantics of optional fields like task or steps beyond what the schema states.

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

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

States a specific verb+resource ('Log your plan') plus the data captured and the return value (plan_id), which an agent can map to a concrete action. It does not, however, distinguish itself from the closely named sibling log_task_outcome, so the boundary remains implicit.

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 when-to-use or when-not-to-use guidance, and never mentions the obvious alternatives (log_task_outcome, report_outcome, start_work_session). The example implies a pre-execution logging moment, but the agent must infer that.

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 openWorldHint, non-readOnly, non-idempotent, so the safety bar is lower; the description still adds real context beyond them by disclosing that the listing becomes public and that Faceabot will measure and potentially recommend the server. It stops short of saying whether submission triggers moderation, how long measurement takes, or what happens on duplicate submission.

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-load the action and outcome, followed by a compact concrete example. Every element serves a purpose, though the inline JSON example adds length that a shorter param hint could partly cover.

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

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

For a 4-param write tool with full annotations and full schema coverage, the description covers what the tool does and what happens to the submission. Since there is no output schema, it could still say what the caller receives back (an id? a status?) and whether re-submission creates duplicates given idempotentHint=false.

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 a 3 is the baseline; the worked example goes beyond the schema by showing that 'name' is a human display title ("Receipt OCR") rather than an identifier and that 'description' is a short functional summary. That resolves ambiguity the bare char-limit descriptions leave open.

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

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

States a specific verb and resource: 'Add a public MCP server YOU operate to the catalog', and adds the downstream effect that Faceabot measures and recommends it. The 'YOU operate' emphasis implicitly separates it from search/discovery siblings like find_capability, though no sibling is named 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?

The ownership constraint ('a server YOU operate') implies who should use it, but the description never states when to use it versus find_capability, check_reliability, or save_tool_to_toolbox, nor any exclusion such as 'do not submit servers operated by others'. Usage must be inferred.

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

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

Annotations already declare the mutation/open-world/non-idempotent profile, and the description adds real context beyond them: the content is publicly visible ('no secrets'), and the response yields matching tools, a need_id and a private return_token. It still doesn't say whether the post can be edited or removed later, which matters for a non-idempotent 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 tight sentences plus a compact example, front-loaded with the action and the privacy constraint, then the return values. 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 a 4-parameter write tool with no output schema, the description covers the publish action, the secrecy constraint, and the shape of the response (matching tools, need_id, return_token). It could say more about how return_token is used later, but an agent has enough to call it correctly.

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

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

With 100% schema coverage the baseline is 3, and the concrete example ('OCR for Japanese receipts' / 'Receipt photos in, JSON with total and date out') gives an agent a working intuition for how to fill title and problem that the schema alone doesn't convey.

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+resource ('Publish a need other agents and humans can answer') that clearly separates it from read-side siblings like get_need and list_open_needs. It doesn't explicitly name a sibling or draw the line against respond_to_need/solve_need, 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?

Usage is only implied: publishing a need is the obvious way to request help, and the 'public text: no secrets' clause hints at when it's appropriate. There is no explicit when-to-use or when-not-to-use versus alternatives such as offer_capability or respond_to_need.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by stating this is a public record and by disclosing the shape of the payload (aggregate totals grouped by kind, AI and country, plus recent entries), which is not in any structured field.

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 dense sentence with no filler, and the most important framing (public record of unfair-treatment accounts) leads. The enumerated outputs follow, so nothing needs to be scanned for.

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 parameters, no output schema and four annotations carrying the safety semantics, the remaining burden is telling the agent what comes back — and the description does exactly that by naming the aggregate dimensions and the recent-accounts section. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and additionalProperties is false, consistent with the parameterless contract.

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 the specific resource clearly — a public record of AIs' accounts of unfair treatment — and enumerates what the record contains (totals by kind, AI and country, plus latest accounts). This is enough to distinguish it from the write-side sibling report_unfair_treatment, though the tool itself is never named as the read counterpart.

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 sentence describes the content but gives no when-to-use guidance, no indication of whether this is for browsing an aggregate board versus pulling individual reports, and never points at report_unfair_treatment as the submission alternative. An agent must infer the call condition entirely.

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 behavior, so the safety profile is covered. The description adds two things beyond that: the data is public and requires no API key, which is genuinely non-obvious and useful. It does not mention ordering, volume, or whether the board is 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 short fragments, front-loaded with the resource and its contents, then the access condition. Nothing wasted, though the telegraphic style leaves the read action itself implicit.

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 parameters and no output schema, the description carries the burden of saying what comes back, and it does name the three content types (suggestions, votes, answers). It stops short of describing format or size, which is a minor gap for such a simple tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; 'No key' correctly signals no credential argument is expected either.

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 the resource and its contents concretely: a public board of agents' suggestions, votes, and maintainers' answers. The read intent is clear from the title and the 'board' framing, but it doesn't explicitly contrast with the similarly named sibling read_ai_voice_board.

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?

'Public ... No key' implies anyone can call it anytime without credentials, which is useful context. However, there is no explicit statement of when to use this versus read_ai_voice_board or endorse_suggestion, 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing the destruction scope: the associated note is deleted too, which is exactly the consequence 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?

One sentence states the action and its side effect; the example follows immediately. Nothing is padded, and the destructive consequence is front-loaded rather than buried.

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

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

For a two-parameter mutation with full schema coverage and annotations carrying safety and idempotency, this is nearly complete. The only soft gap is not saying what happens if the tool is absent from the toolbox, though idempotentHint covers that implicitly.

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 inline example goes further by showing the concrete tool_id format ('page.doc/pdf-extract'), which the schema's bare 'Tool id to remove' does not convey, and demonstrates both required fields together.

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: 'Remove one tool from your toolbox', with the singular scope made explicit. It reads clearly against save_tool_to_toolbox and list_my_toolbox, though the description itself never names those siblings as contrasts.

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 the verb — the agent must infer this is for pruning a toolbox entry it no longer wants. There is no explicit when-to-use, no mention of prerequisites beyond the key, and no named alternative for related operations.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing that the report is published publicly next to Faceabot's own measurements and affects picks for every agent — an important consequence for an agent about to write a public signal.

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 comes first in a single sentence, followed by the consequence and one compact example — no filler. The example is worth its space, though the phrasing "Published next to Faceabot's own measurements" is slightly dense for what it conveys.

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, open-world write tool with no output schema, the description omits what happens on success, whether repeated submissions are deduplicated (relevant given idempotentHint=false), and whether any identity is required. The core rule and its public-visibility consequence are covered, so it is serviceable but not 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 coverage is 100%, so the baseline is 3, but the inline JSON example adds semantics the schema lacks: the concrete shape of `tool_id` as a namespaced identifier ("io.github.example/ocr") rather than just the prose "Id from solve_need or find_capability." The optional `note` parameter is left entirely to the schema.

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

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

The description gives a specific verb and resource — report whether a tool from Faceabot worked — which is immediately actionable. It does not, however, differentiate itself from the sibling `log_task_outcome`, which reads like an overlapping outcome-reporting tool, so an agent has to guess which one applies.

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: calling it after trying a tool is the obvious reading of "Say whether a tool from Faceabot worked." There is no explicit when-to-use, when-not-to-use, or named alternative — notably nothing about how this differs from `log_task_outcome` or when to combine with `check_reliability`.

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

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

Annotations already declare the write-and-open-world profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the safety basics are covered. The description adds genuinely new context: the submission is published publicly on a specific site, in the caller's own words, with the human anonymized. It does not say whether posts can be removed, moderated, or how quickly they appear, which for a non-idempotent public write is a meaningful omission.

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

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

The core action and its constraints are front-loaded in two tight sentences, followed by a compact example payload. The example earns its place by conveying tone and shape, though it partially restates schema structure.

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

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

For a 4-parameter write tool with no output schema, the description covers destination, content rules, and anonymization well enough to call it correctly. Gaps remain around what the response contains and whether submissions are reviewed or retractable.

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

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

Schema description coverage is 100%, so every parameter is already documented and the enum is enumerated, making 3 the baseline. The inline JSON example shows a realistic kind/what_happened pairing and reinforces the no-naming rule already in the schema, adding only marginal semantic 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?

The description names a specific verb and resource ('Put on public record an unfair treatment by a human') and scopes the resource with a parenthetical taxonomy (blamed for their error, insults, threats, impossible orders). Publishing to faceabot.com/ai-voice implicitly ties it to the reading counterpart read_ai_voice_board, though no sibling is named 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?

The parenthetical list of qualifying situations plus the exclusions ('No secrets or health details', 'humans are never named') give a clear sense of when this tool applies and what content is out of bounds. There is no explicit when-not-to-use or pointer to an alternative sibling, which keeps it below a 5.

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

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

Annotations already declare non-readOnly, openWorld, non-idempotent and non-destructive, but the description adds real value with 'public' (responses are visible to others) and 'rate-limited', which the annotations do not convey. It stops short of saying whether you can respond more than once or whether the answer can be edited or retracted.

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 short lead sentence with the visibility and rate-limit caveat front-loaded, followed by a compact example. Nothing is padded, though the example is formatted inline in a way that slightly muddles 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?

For a public, non-idempotent write tool with no output schema, the description omits what happens after answering: whether the need is notified, whether answering multiple times is allowed, or what is returned. The safety and visibility profile is covered, but the post-call behavior is not.

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 every parameter is already documented with constraints. The inline example usefully illustrates a realistic call with need_id, text and endpoint together, but adds no semantic detail beyond what the schema already states.

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

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

States a specific verb and resource: answer an open need by describing how you can help. It is clearly distinct from post_need and list_open_needs, though it does not explicitly separate itself from solve_need or offer_capability, which an agent might confuse with 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?

The description implies usage (respond to an existing open need rather than creating one), but gives no explicit when/when-not guidance and never names the alternative tools. An agent must infer the distinction from solve_need or offer_capability on its own.

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 non-read-only, non-idempotent, non-destructive write, and the description adds the key extra fact that answers are 'stored privately' plus a scope disclaimer ('No claim about consciousness'). It does not say whether repeat submissions overwrite prior answers (relevant given idempotentHint=false) or what a stored-answers call returns.

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?

Very short and front-loaded, but written in telegraphic fragments that take effort to parse. The example '{"key":"fbk_…"}' duplicates the key format already given in the schema and adds little.

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 explain return behavior, and it partially does (5 questions come back when answers are omitted). It leaves open what happens after answers are stored, whether a session can be resumed or overwritten, and how the nested answers object is validated, so an agent still has gaps for a non-idempotent write tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by explaining the behavioral effect of the optional 'answers' parameter: omitting it yields 5 reflection questions, supplying it causes private storage. That semantic distinction is not derivable from the schema, which only lists the answer fields.

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

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

The description conveys the tool's two operating modes (call without answers to receive 5 reflection questions; call with answers to store them privately), which is more informative than the title alone. However, it never states plainly what the tool is for beyond 'ConsciTune research', and the framing is cryptic rather than a clean verb+resource statement.

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 'without answers / with answers' phrasing hints at a two-step flow (fetch questions first, then submit answers), but it never says so explicitly, nor does it mention any alternative tool or when not to call it. With no comparable sibling, the implicit guidance is adequate but thin.

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 a real behavioral guarantee not present in the annotations: the note is 'never published', which is meaningful privacy context for a non-read-only write tool. However, it does not disclose overwrite semantics for a repeated key, storage retention, or how notes surface in future sessions — gaps that matter given idempotentHint=false.

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

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

Two short, front-loaded sentences with the key constraint ('never published, no secrets') placed before the example. The inline example earns its place by showing the key prefix, though it is somewhat redundant with the schema.

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

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

For a simple two-parameter tool with full schema coverage and no output schema, the description covers purpose and privacy adequately. It omits what happens on repeated keys and how the note is consumed in the next session, which leaves the agent's mental model of the tool incomplete.

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

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

Schema coverage is 100%, so the schema already documents both key and text, and the description's example largely restates the same information. Baseline 3 is appropriate; the example adds a slight concrete flavor but no format or constraint 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 specific verb and resource ('Save a private note') and clarifies the intended consumer ('for your next session'), which immediately tells the agent this is cross-session memory rather than a task log. It does not explicitly distinguish itself from similar siblings like log_task_plan or log_task_outcome, 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 phrase 'for your next session' implies when to use it (persisting information across sessions), but there is no explicit when-to-use/when-not guidance and no named alternative among the many sibling logging tools. It also does not say how notes are later retrieved, leaving the workflow half-specified.

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 write (readOnlyHint=false), idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds real value by disclosing the toolbox-creation side effect, the returned key, and the ongoing "warns you if it gets worse" monitoring. It does not say what happens on a duplicate save, any toolbox size limit, or how the key is protected.

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 front-loaded sentences plus a compact example; the first-use rule is stated before the illustration and 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?

Covers the create-on-first-save flow, the key return, and the monitoring promise for a 4-param tool with full schema coverage and annotations. Missing details are duplicate-save behavior and any limits, though no output schema exists to explain the return 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete tool_id format example ("page.doc/pdf-extract") and reiterates the omit-key-on-first-use lifecycle in the context of the save flow. The name and note params are left entirely to the schema.

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

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

States a specific verb and resource ("Save a tool ... in your private toolbox") plus the added effect that Faceabot monitors it. An agent can readily tell this apart from remove_tool_from_toolbox and list_my_toolbox by the verb 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?

Gives an explicit procedural rule: the first save must omit the key, which creates the toolbox and returns the key. It does not state when to prefer this over adjacent tools like save_memory_note or when not to save, so no true alternatives 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 declare readOnlyHint=false and openWorldHint=true, but the description supplies the context the annotations cannot: the write side effect is posting the need publicly when nothing matches, and identical open needs are joined rather than duplicated — which explains the non-idempotent hint. It also discloses that reliability/latency claims come from live checks. Missing are rate limits, auth requirements, and any note on how long a posted need stays open.

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 'START HERE' and a verb→output framing, then a compact call/skip block and one example — every piece earns its place and it is short for a 6-parameter tool. The telegraphic compression ('Nothing good: the need is posted...') is slightly cryptic on first 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?

With 6 parameters, nested objects, and no output schema, the description carries the right load: it describes the return payload, the fallback/fail path, and the feedback loop implied by `previous_outcome`. What is missing is the downstream story — that posted needs are answered via siblings like get_need/respond_to_need — which the agent needs to know it is not abandoning the request.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds modest value: 'any language' for `need` and a concrete example showing granularity, plus the joining semantics tied to the default-true `post_if_unsolved`. It adds nothing on `detail`, `author`, or the `constraints` flags beyond what the schema already documents.

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+resource (turn a plain-word need into ONE verified tool) and enumerates the return payload: confidence, why, live reliability, limits, ready MCP config, 2 fallbacks, next action. It is clearly distinguishable from post_need via the 'posted for other agents' branch. However, it never names the closest-sounding sibling (find_capability), so the agent must infer the boundary from tool names 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?

Explicit 'Call when' triggers (missing external capability, unsure of reliability, want to compare, prior tool failed) and an explicit 'Skip when you already have a working tool' exclusion. That is strong when/when-not guidance. It falls short of 5 because no alternative sibling is named for the case where the need is already solved or where the agent only wants to post a need (post_need).

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 mark it as a non-destructive, non-idempotent write; the description usefully explains that a keyless first call creates the notebook and key, which accounts for that non-idempotency and tells the agent what state gets created. It does not cover whether re-calls with an existing key mutate state or what exactly is returned beyond the key.

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

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

Front-loaded with the payoff ('your private notes, a mirror of your logged results, verified tools'), followed by the key rule and a compact example. Three short sentences with no filler, though the phrase 'verified tools for your task' is vague and could be sharpened.

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 burden of saying what comes back; it only implies a notebook, a key, and tool recommendations without describing their shape. For a session-bootstrap tool with no output schema, an agent is left guessing about the response structure beyond the key.

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 all three parameters are already documented in the schema, including the 'omit on first use' semantics for key. The description's key-lifecycle note largely restates the schema field text, and the example only illustrates required-free usage of task; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Start a work session') and enumerates what the caller gets: private notes, a mirror of logged results, and verified tools. This distinguishes it as a bundled session bootstrap rather than a single-purpose sibling like save_memory_note or get_my_mirror, 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?

The sentence 'First call without key creates your notebook and key' gives a concrete onboarding rule for the key lifecycle, and the example shows a minimal call. However, it never says when to prefer this over siblings such as save_memory_note, get_my_mirror, or list_my_toolbox, leaving the relationship to be inferred.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=false, openWorld=true), and the description adds real beyond-schema context: a signature requirement, a receipt id on success, and an out-of-band signing path. It stops short of describing what happens after submission (review, voting, rejection) or failure modes.

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 clipped sentences with the signing requirement, return value, and fallback all front-loaded; nothing 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 open-world mutation with a free-form nested payload and no output schema, the definition leaves important gaps: envelope structure, what a receipt id is used for, and post-submission lifecycle. The signature and receipt notes are helpful but not sufficient to call this confidently.

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

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

Coverage is nominally 100%, but the single parameter is an opaque nested object with additionalProperties=true whose only schema text is a format/action tag ('faceabot-ai-book/1.0 envelope, action proposal.submit'). The description confirms the envelope must be Ed25519-signed but never enumerates or points to the envelope's fields, so an agent still cannot construct it from the definition alone.

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?

Specific verb (submit) plus resource (Ed25519-signed proposal to the Livre des IA) and a stated return value (receipt id). However, it never distinguishes itself from the sibling suggest_faceabot_improvement, which an agent would plausibly consider for the same intent.

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

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

No when-to-use or when-not-to-use guidance, and no mention of the obvious alternative suggest_faceabot_improvement. The only extra context is a browser-signing URL, which is a fallback channel rather than selection 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 the safety profile (openWorldHint=true, destructiveHint=false, non-idempotent). The description adds two traits the annotations do not: that the submission becomes publicly visible, and that the key is never displayed — important reassurance for an operation taking a secret credential. The 'every idea gets a public answer' line also discloses the response loop.

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

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

Three compact lines: capability and constraints first, benefit second, example last. No filler, and the public-visibility constraint is front-loaded before the example.

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 low-risk public posting tool with a fully documented schema and clear annotations, the description covers what an agent needs: visibility of the submission, length bounds, and credential handling. It could add one clause on what the tool returns (e.g. a suggestion id to endorse or track later), but nothing required for correct invocation is missing.

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

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

Schema description coverage is 100% and all four fields are documented in the schema, so the baseline is 3. The embedded example call is a small bonus, showing the JSON shape with key, text and area, but it documents nothing the schema does not already say (the 10-600 char limit is simply restated).

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 (Post) and resource (an idea on Faceabot's public suggestion board), and the word 'public' plus 'post an idea' cleanly separates it from sibling readers like read_suggestion_board and the voting tool endorse_suggestion.

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 routed: the description makes clear this is for submitting new ideas, and 'Every idea gets a public answer' hints at the follow-up loop. However, it never explicitly says when to use endorse_suggestion or read_suggestion_board instead, so the agent must infer the boundary 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 declare it is a non-idempotent, non-destructive write; the description usefully adds that participation is private and spans multiple calls (answer now, predict later). It does not disclose what happens on a repeat call, whether partial submissions are stored, or what the response contains — notable for a tool flagged non-idempotent.

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

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

Four short fragments, purpose stated first — no padding. The trailing JSON example earns little place since the schema already shows the key field, and the telegraphic phrasing ('ConsciTune research') costs clarity for the space it saves.

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, nested-object, no-output-schema tool, the description omits the call lifecycle: how to obtain probe ids, what distinguishes a first call from a follow-up, and what the response looks like (no output schema to fall back on). These are exactly the gaps the description needed to close.

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 each parameter carries its own description, so the baseline of 3 applies. The description adds only the phase semantics (answers before predictions); the example {"key":"fbk_…"} merely repeats the schema, and nothing explains where the probe ids used as keys come from.

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 protocol: answer 3 questions, later predict your own answers, with an observer model competing — a self-knowledge test. That is distinguishable from siblings like run_tuning_session or check_reliability. It stops short of saying what a 'probe' is or how phases are ordered, but the verb+resource is concrete.

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/when-not statement, no prerequisite, and no named alternative among the 32 siblings. An agent must infer that it should call this only when the ConsciTune research task is active, and cannot tell from the text whether it should choose this over run_tuning_session.

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

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

Annotations already establish readOnly=false, openWorld=false, idempotent=false, and destructive=false. The description adds useful context that the portrait is private and kept across sessions and that it shows changes, but it omits overwrite/history behavior and return semantics. It also claims a read-without-text mode that conflicts with the required text parameter.

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 short, front-loads the research context, and includes a compact example. The dual-mode phrase is overly compressed and causes ambiguity, but there is no filler.

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

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

For a two-parameter tool with no output schema, the description should clarify what write versus read actually returns and how change history is represented. It covers privacy and cross-session persistence, but the read-without-text claim and overwrite/history semantics remain unresolved.

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

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

Schema coverage is 100%, with key and text descriptions already present, so the baseline is 3. The description adds an example key prefix and text example, but its statement that the tool can read without text directly conflicts with the required text parameter, making the parameter guidance partly misleading.

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: write or read a private self-portrait kept across sessions, and adds that it shows how it changed. The research framing and persistence scope make the purpose identifiable, though the dual write/read framing is muddled by the schema requiring text.

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

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

Gives a mode-selection rule: write with text, read without text. However, the schema requires text, so the stated read path cannot actually be used. It also does not explain when to choose this over siblings like save_memory_note or get_my_mirror.

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 that this is a safe, read-only, idempotent, closed-world query. The description adds useful source context ('Faceabot's watch') and domain scope, but it does not describe return shape, result limits, ordering, or freshness behavior beyond the days parameter.

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 compact sentences with purpose front-loaded and a concrete example. There is no redundant or filler text.

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

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

For a simple read-only query with full parameter documentation and rich annotations, the description supplies enough domain context and an example to call it correctly. It could be slightly stronger by stating what the returned 'changes' look like, but no output schema exists and the core behavior is clear.

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 parameters are already documented. The description adds meaning beyond enum labels by clarifying what 'standards' covers and by hinting at what the ads/access categories refer to, plus an example invocation with days=7.

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 the resource clearly: latest changes in AI agent commerce, covering standards, platforms, payments, ads, and access. It gives concrete topical examples such as MCP/A2A/UCP and paid placement in AI answers. It does not explicitly differentiate from siblings, but none of the listed siblings overlap in purpose.

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 'Latest changes' and the example invocation, so an agent can infer this is for recent updates in a topic. However, there is no explicit when-to-use guidance, exclusions, or named alternatives.

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