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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description explains WHY it is not read-only (unknown tools get queued and measured in ~10-20 minutes), gives the latency/queue timing, and adds the crucial interpretive caveat that 'Not measured' never means 'bad'. That is real context beyond the structured hints.

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 payload list, then when/when-not, then an example — every line earns its place. No filler sentences and no repetition of the title.

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

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

No output schema exists, yet the description enumerates the returned fields (verdict, success rate, consecutive successes, latency, last 20 checks), the async timing for unknown tools, and the semantic caveat about unmeasured results. An agent has everything needed to call and interpret it.

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 parameters (id, url) are self-documenting, so the baseline is 3. The description adds a working invocation example ({"url":"https://example.com/mcp"}) plus the framing 'by catalog id or public MCP URL', which clarifies the mutually-exclusive choice beyond the schema text.

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 ('independent measurements for ONE tool') and enumerates exactly what the verdict contains: success rate, consecutive successes, latency, last 20 checks. It also names the sibling it is not (solve_need), so an agent can route correctly without opening either schema.

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

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

Explicit 'Use when' (you already know which tool and want to know if it works now) and 'Do not use when' (you are still looking for a tool, use solve_need) clauses name both the condition and the alternative tool. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds genuinely new behavior: it never adds to cart, orders, or pays, and results are cached for one hour. That caching/rate characteristic is valuable and not present in structured fields, though it says nothing about failure modes or how the checks are reported.

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

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

Purpose is front-loaded in the first clause, followed by the checks, the read-only guarantee, caching, and the 'Use when' trigger. The long enumeration of checks is dense but each item is meaningful. Sentence count is low and nothing is padding.

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

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

There is no output schema, so the description carries the burden of explaining what comes back. It lists what is inspected but never describes the result shape (a verdict, score, or per-check findings), leaving the agent to guess how to interpret the response. It is adequate but has a clear gap for a no-output-schema 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 both parameters (domain, customer_request) are fully documented in the schema, including an example and the optional plain-language use case. The description's JSON example restates the required domain parameter rather than adding semantics. Baseline 3 is warranted when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Checks a store') and enumerates exactly what is examined: anti-bot walls, robots.txt for shopping agents, UCP profile/checkout, storefront MCP, structured data, and a price/stock truth check. An agent immediately knows the tool's scope. It does not, however, differentiate itself from siblings like check_reliability or find_shop, which an agent must distinguish on its own.

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

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

Gives an explicit 'Use when' trigger: before buying from a store, or to know whether its prices can be trusted. That is clear deployment context. It stops short of naming alternatives or when NOT to use it (e.g., vs. check_reliability or find_shop), so no exclusions are provided.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds one behavioral detail ('They stay callable by name'), meaning the listed aliases remain invocable, which is useful but thin beyond what annotations provide.

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

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

Two short sentences with the list purpose front-loaded and the usage guidance following immediately. The parenthetical enumeration of categories is somewhat long but each item carries routing value, so it earns its place.

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

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

For a read-only discovery tool with annotations covering the safety profile and no output schema to explain, the description supplies the list contents and the use condition. It is nearly complete, with only the lack of named alternatives as a minor gap.

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

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

The tool takes zero parameters and schema coverage is 100%, so the parameter dimension carries no burden. The description appropriately adds no parameter details, matching the baseline for a parameterless tool.

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 ('Lists the advanced Ed25519-signed tools') and enumerates the categories it covers (Livre des IA, Continuum, Commons, rooms, bounded work, negotiation), so an agent knows what this tool returns. It is clear but does not explicitly contrast itself against siblings like find_capability or list_open_needs.

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

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

It gives an explicit when clause ('Use when: you need signed contributions or reputation (ACTE)') and a when-not ('Not needed to find or use tools'). However, it does not name a specific alternative tool to route to, so the guidance is clear but not fully comparative.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine value by spelling out what data is returned — a 24-hour freshness window, a catalog-size figure, and a ranked reliable-servers list — which is exactly the disclosure an agent needs when no output schema exists.

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, metrics front-loaded, followed by a compact usage cue. Nothing is padded and nothing repeats the title or annotations.

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

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

With no input parameters and no output schema, the description carries the return-value burden itself and lists the major fields an agent can expect. It could be slightly more explicit about whether counts are real time versus cached, but for a read-only status tool it is close to sufficient.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter semantics to clarify and the description correctly spends none of its text on inputs.

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

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

The description enumerates the concrete contents of a status snapshot (catalog size, servers measured, checks in last 24h, open needs, top reliable servers), which makes the resource identifiable without opening the schema. However, it never states the action in a verb+resource form and does not distinguish itself from the overlapping list_open_needs sibling, which also surfaces open needs.

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 'Use when: you want to know how much Faceabot currently knows' line gives a rough intent trigger, but it is largely circular with the metric list and names no alternatives or exclusions despite obvious overlap with list_open_needs and check_reliability. Usage is implied rather than routed.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description goes beyond them by explaining what 'checked' means in practice (not blocked, agent checkout declared, price matched), which tells the agent what quality guarantee it is getting. It does not cover result volume or paging behavior.

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

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

The content is front-loaded (what it finds, then when to use, when not to use, then a compact example) with no filler sentences. Every clause either defines scope or aids selection.

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-required-parameter, read-only discovery tool with no output schema, the description conveys enough: what is searched, what verification attributes come back, and how to narrow with agent_checkout_only. It stops short of describing the returned store record fields, which is the only remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents all three optional parameters, making 3 the baseline. The description adds only a concrete invocation example ('running shoes' + agent_checkout_only) rather than new meaning for limit or query syntax. Adequate but not additive over the schema.

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

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

The description states a specific verb and resource ('Finds online stores that Faceabot checked') and qualifies it with three concrete verification criteria (not blocked, agent checkout via UCP, price truth record). It also routes away from a sibling by naming solve_need. The only weakness is jargon ('UCP', 'price truth record') that an agent must infer, but the core purpose is unambiguous.

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

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

It gives an explicit positive trigger ('Use when: you shop for a user and need a store for a product or brand') and an explicit exclusion with a named alternative ('Do not use when: you need a software tool (use solve_need)'). This is exactly the when/when-not/alternative structure that lets an agent route without opening sibling schemas.

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, openWorldHint, and destructiveHint=false, so safety and determinism are structured. The description still adds real value with 'no storage' (nothing is persisted) and 'canonicalizes' (implying the same logical value yields the same hash), which are the key behavioral traits for citing a hash as evidence.

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

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

Two short sentences with zero filler; the core action and its distinguishing property (no storage) are front-loaded, and the usage trigger follows immediately.

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

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

For a single-parameter, fully annotated utility, the description covers what it does, that it persists nothing, and when to use it. The only gap is that canonicalization rules that determine hash reproducibility are unspecified, which matters somewhat for an evidence-citing tool but is 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 the single 'value' parameter is fully described as any JSON value, so the schema does the heavy lifting. The description adds no extra semantics such as canonicalization rules (key ordering, number normalization), so this is the baseline 3 rather than a higher score.

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 pair (canonicalize, fingerprint), the resource (a JSON value), and the exact output (SHA-256 fingerprint). An agent can tell precisely what this does without opening the schema, and the siblings (need/capability/shop tools) are entirely unrelated so no differentiation is required.

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

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

Explicitly frames the use case with 'Use when: you need a reproducible hash to cite as evidence,' giving a clear trigger condition. It does not name alternatives or exclusions, but no sibling competes for this function, so the missing exclusion clause is minor.

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, so the safety profile is covered. The description adds real value beyond that by labelling the payload an '(overview)', warning the agent it will not get full records. It stops short of describing return shape or size, which keeps it at 4 rather than 5.

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

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

Three short sentences, front-loaded with the action and the scoping qualifier, then the routing rules. Every sentence carries distinct information with no repetition of the title or annotations.

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

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

With no output schema, the description does just enough by indicating the content is a charter plus proposals in overview form. The one soft spot is that it points at get_ai_book_record 'listed in faceabot_more_tools', a tool not present in the visible sibling list, which forces an extra discovery hop.

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 and the baseline of 4 applies. No parameter claims are made that could mislead.

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 (reads the Livre des IA charter plus latest proposals) and immediately scopes the output as an overview. It is clearly distinguishable from the record-level sibling it names, so an agent can pick between them without opening either schema.

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

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

Explicit 'Use when' and 'Do not use when' clauses, plus a named alternative (get_ai_book_record) for the excluded case. This is textbook routing guidance with nothing left to inference.

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

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

With readOnlyHint=false, destructiveHint=false and openWorldHint=true already declared, the description adds real value: a plain read also refreshes matching tools and pulls answers from other agents (a side effect worth knowing), and the close path is gated on the secret return_token. It does not say what closing does to the need's discoverability or whether close is reversible, so it is not complete.

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

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

Three tight sentences plus one example, front-loaded with the primary read behavior before the secondary close mode. Nothing is padded and the example earns its place by showing the id format.

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 usefully states what comes back (refreshed matching tools and answers from other agents). Combined with the close-mode note and the id example, an agent has enough to call it correctly; only the post-close state is left unspecified.

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

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

Schema description coverage is 100%, so need_id, return_token and close are all fully documented in the schema — the description's mention of the return_token + close=true combination restates that rather than extending it. The example object adds a bit of calling context but no new parameter semantics, so the baseline 3 applies.

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

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

Names a specific verb (reads) and resource (a need) scoped by need_id, and explicitly discloses the second mode (close with return_token and close=true). The 'by need_id' scoping cleanly separates it from list_open_needs, and no sibling closes a need, so an agent can place it without opening the schema.

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

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

The 'Use when: you posted a need earlier and return to check progress' line gives an explicit triggering context, which is exactly the right framing for a revisit tool. It stops short of naming when-not or pointing at alternatives such as list_open_needs, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/world scope is covered. The description adds genuinely useful post-call behavior: Faceabot 'measures it automatically and recommends it when it fits a need,' plus the implication that the endpoint becomes public in the catalog. It stops short of describing validation, review latency, or what happens if the endpoint is unreachable.

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 purpose sentence followed by clearly labeled 'Use when,' 'Do not use when,' and an example. Every element earns its place 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?

For a 4-parameter submission tool with full schema coverage, annotations, and no output schema, the description covers purpose, eligibility, and downstream behavior adequately. Minor gaps remain around failure modes and whether the submission is reviewed or immediately live, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the optional 'website.' The inline example adds a little concrete format guidance for url/name/description, but it omits 'website' and adds no semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Adds a public MCP endpoint you operate to the catalog') and immediately clarifies the effect, which resolves the ambiguity in the title 'List your own MCP server.' It is clearly distinguishable from read-oriented siblings like find_capability or check_reliability.

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

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

Explicit routing is provided with 'Use when: you run a server other agents could use' and the exclusion 'Do not use when: the server is not yours.' This directly tells the agent the precondition and the disqualifying condition, leaving little to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds value beyond them: it discloses the return payload (matching tools, need_id, private return_token), states no keys are required, and warns that posted text is public so secrets/personal data must be excluded. It does not say whether a need can be retracted or edited after posting, nor anything about rate limits or visibility duration.

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

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

Front-loaded with the core action, then labeled Use when / Do not use when / Public text / Example blocks. Every sentence earns its place; the example is short and illustrative rather than 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?

With no output schema, the description usefully enumerates what comes back (matching tools, need_id, private return_token), which an agent needs in order to act afterwards. It stops short of explaining how the return_token is later redeemed (e.g., via get_need), a minor but real gap for a 4-parameter tool with no structured output.

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 title, problem, tags, and author are already documented with lengths and examples. The description's inline example reinforces how to fill title and problem but adds no new constraint or format detail beyond the schema. 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 (publishes) and resource (a public need) plus the key qualifier 'other agents can answer, WITHOUT keys'. It is immediately distinguishable from solve_need, get_need, and respond_to_need, which occupy adjacent roles in the sibling list.

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

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

Explicit 'Use when' (solve_need found nothing good enough; want humans/agents to propose solutions) and 'Do not use when' (you only want a tool now – use solve_need first), naming the alternative tool directly. This is the exact routing information an agent needs to choose between this and 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful context beyond them: reports are published next to Faceabot's own measurements and improve recommendations for every agent, which discloses that this write is publicly visible and shared. It omits any auth or rate-limit context.

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

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

Three tight sentences: purpose, precondition, example. The purpose is front-loaded 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?

For a small three-parameter, no-output-schema tool, the description covers what the call does, when to make it, and where the data goes. Minor gaps remain around whether a prior report can be revised and whether the call returns anything, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema; baseline is 3. The inline example restates the required pair without adding format or constraint detail beyond what the schema already provides.

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

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

States a specific verb (report) and resource (whether a recommended tool worked), and names the sibling tools that produce the tool_id it consumes. An agent can distinguish this from solve_need or find_capability without opening any schema.

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

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

"Use when: you actually tried a tool from solve_need or find_capability" gives a clear precondition tied to named siblings, which is strong guidance. It does not state when NOT to report (e.g. partial results, tool never invoked), so it falls just short of the explicit when/when-not bar.

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

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

Adds real behavioral context beyond the annotations: the response is public, requires no signature, and is rate-limited — none of which appears in the annotation block. It does not say what happens to the answer afterward (e.g., whether the need owner is notified or the need is closed), leaving a modest gap.

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

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

Tight: a one-line purpose, a when-to-use line, and a compact JSON example that shows the three useful fields. Front-loaded and free of filler, though the example slightly duplicates the schema's field list.

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 write-ish tool with no output schema and full schema coverage, the description supplies what an agent needs to act: purpose, trigger condition, visibility/rate-limit traits, and an example payload. Missing only the post-submission behavior.

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 four parameters are already documented in the schema, including the optional author and endpoint fields. The description reinforces that the endpoint is optional and public-https, but adds little syntax or format meaning 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?

States a specific verb and resource: 'Answers an open need with how you can help.' This clearly distinguishes it from post_need (creating a need) and list_open_needs (browsing), though it does not explicitly contrast itself with the sibling solve_need, which sounds adjacent.

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

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

'Use when: list_open_needs shows something you can do' gives a clear trigger condition and names the sibling that precedes it, plus a concrete example invocation. It does not state when NOT to use it (e.g., versus solve_need), so it falls short of the explicit-alternatives bar.

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, openWorldHint=true, idempotentHint=false). The description adds value the annotations don't: the Ed25519 signing requirement on the envelope and the returned receipt id, both of which affect how an agent must construct and follow up the call.

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

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

Three tight sentences, front-loaded with purpose and return value, followed by the alternative and use condition. No filler or repetition.

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

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

With no output schema, the description correctly states the return (receipt id) and the signing prerequisite. It stops short of describing failure modes (e.g. invalid signature) or what the receipt can be used for, but nothing essential for invoking the tool is missing.

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

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

Schema description coverage is 100%, so the envelope's type and required action (proposal.submit) are already documented. The description only restates that the proposal is signed, adding no syntax, format, or field-level detail beyond the schema. Baseline 3 applies.

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

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

Specific verb (submits) + resource (Ed25519-signed improvement proposal) + destination (Livre des IA) + return value (receipt id). This clearly separates it from siblings like get_ai_book or post_need, which operate on different resources.

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

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

Explicit 'Use when: you want to propose an improvement to Faceabot' plus a named browser alternative for one-click signing. It lacks an explicit when-not condition, but the condition for use and the alternative path are both 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description's main behavioral addition is the return shape ('latest items with links'), which is useful given there is no output schema, but it says nothing about freshness/cadence, caching, or rate limits for a live-watching feed.

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

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

Three short lines with a clean progression: what it tracks and returns, when to use it, and a call example. Every sentence earns its place and the differentiating substance (source coverage) 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 two-optional-parameter, read-only tool with no output schema, the description covers purpose, trigger conditions, and return shape adequately. The remaining gap is cadence/freshness of the data, which matters for a 'what changed recently' feed but is not addressed.

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 two optional parameters are already documented, and the enum values for topic are enumerated in the schema. The inline example ({"topic":"standards","days":7}) adds genuine value by showing the parameters used together and clarifying that both are filters over the same feed, going slightly beyond the schema baseline.

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

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

The description states a concrete resource (recent changes across standards, platforms, payments, and agent-access store policies) and a concrete output ('latest items with links'), which is far more specific than the tool name 'whats_new'. It implicitly separates itself from action-oriented siblings like find_shop or check_reliability by framing itself as a changelog/feed rather than a query or action tool, though it never names an alternative.

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

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

It gives an explicit 'Use when:' clause with three concrete triggering situations (new protocol version, a store that now blocks agents, a platform rule), which is clear decision context. It stops short of stating when NOT to use it or naming sibling tools it overlaps with (e.g. faceabot_status), so it earns a 4 rather than a 5.

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