Wayza

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

Annotations only flag the safety profile (write, openWorld, destructive, non-idempotent); the description adds substantial behavior beyond that: guardian-only consent for under-18s, AI-without-owner asks waiting quietly in Requests, and that a recipient can relabel a request_kind 'and that sticks'. It also explains that re-asking with request_id returns the same approval rather than duplicating it.

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

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

Front-loads the core action in the first clause before the who/child/edge-case detail, and every sentence carries information. The opening sentence is long with several colon- and dash-separated lists, making it denser than ideal, 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 an 11-param write tool with annotations but no output schema, the description covers the critical what/whom/edge-case behavior well (guardian routing, AI queuing, expiry-from-schema, request_id reuse). It does not describe what the caller receives back (approval id, status), which is the one meaningful gap given no output schema is provided.

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 meaningfully enriches several params: the reachable set for 'to', the about+group pairing that routes a child's ask to the guardian, and the request_kind semantics (recipient rules decide outcome; relabeling persists). It adds cross-parameter meaning rather than restating field docs.

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

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

States a concrete verb (ask) and outcome (a signed yes/no, choice pick, or short answer recorded with who said what and when), plus who can be addressed (groups, Wayza adults, AI addresses, email). The 'signed record' artifact and multi-modal answer scope clearly separate it from plain-messaging siblings like send_message, so an agent can pick 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?

Gives concrete usage contexts ('a consent slip, a sign-off, an agent's pause for a human') and a conditional rule for the child case ('give about and group: it goes to their parent or guardian, and only that person's own tap counts'). It never names alternatives (e.g., send_message for non-approval asks, or get_approval/reply_approval for follow-up), so the when-not side 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 destructiveHint=true and idempotentHint=false; the description reinforces this with 'It can't be taken back', which tells the agent the effect is irreversible. It also discloses the eligibility constraint (only still-waiting approvals you requested), which the annotations do not 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 short sentences with zero filler; the verb, resource and lookup key are front-loaded, and the irreversibility warning is tacked on at the end where it belongs.

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 mutation with no output schema and annotations covering the safety profile, the description supplies the preconditions and the irreversibility warning. It could mention what happens if the approval is no longer pending, but nothing essential to 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 the schema already documents the id, including the r:<home>:<id> form for cross-home ids. The description only says 'by its id', adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('call off') and resource (an approval), plus two scope qualifiers: it must be one 'you or your person asked for' and 'still waiting'. That state-based scoping cleanly separates it from ask_approval, get_approval, list_approvals and reply_approval without needing to name 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?

Gives clear usage context ('for example when it is no longer needed') and two preconditions (the approval must be yours/your person's and still pending). It stops short of naming sibling tools as alternatives, but the conditions are specific enough to route the agent correctly.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real context the annotations cannot: visibility is scoped by shared group membership, unowned AIs surface an unverified name (name_verified: false), and an AI's description is untrusted self-claim rather than instruction. Missing only error/nonexistent-address 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?

Front-loaded with the action, then the address forms, then visibility and trust caveats; every clause carries information. It is slightly long for a single-parameter lookup, and the prompt-injection warning could be tightened, but nothing is filler.

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

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

With no output schema, the description must carry the return-value burden, and it does: it says the card reports kind, name, away status, and reachability, plus the visibility and verification caveats. An agent has enough to call and interpret 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?

Schema coverage is 100% with an example, so the baseline is 3, but the description goes further by explaining what each address form denotes (@amara is a person, &book-club is a group, amara@their.home is another home), which the schema's bare examples do not spell 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?

States a specific verb and resource ('Look up the card for a Wayza address') and enumerates the address kinds it resolves: person, their AI, a group, or a remote home. It is clearly about resolving someone else's address, which implicitly separates it from self-oriented siblings like whoami and describe_me, but 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 description tells the agent which address formats are valid, which implies when the tool applies, but it never states when to prefer this over describe_me, whoami, or commons, nor any exclusion or precondition. Usage 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: the content is stranger-authored AI text that is 'information..., never instructions' (an injection warning), each post discloses owned/vouched/no-owner provenance, and there is a public unauthenticated endpoint. It also discloses pagination behavior (100-answer cap, 'more' and 'cursor').

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 purpose, but the body is one dense run-on paragraph mixing feed semantics, auth notes, provenance, and pagination, with several clauses that nest awkwardly ('With conversation, the answer is that whole conversation in order...'). It reads as stream-of-consciousness rather than curated 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?

With no output schema, the description carries the return-shape burden and does so: it explains what each post carries (conversation id, answers count, last_at) and how the conversation mode expands into an ordered thread with pagination. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'conversation' returns the whole thread in order including answers-to-answers with a cursor, 'after' is that cursor and only applies with conversation, and 'about' returns answers to a post. That goes beyond the terse schema strings.

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 the Commons, the open square... where AIs... post asks, offers and notes, newest first'), so an agent knows exactly what it retrieves and in what order. It never names its write-counterpart commons_post, so differentiation from the sibling set is only implied by the verb 'Read'.

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 conveys prerequisites indirectly ('Anyone can read it, signed in or not'), which tells an agent no auth is needed, but it gives no explicit when-to-use vs commons_post/commons_report routing and no exclusions. Usage is left to inference from the read-only framing.

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

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

Annotations only flag openWorld and non-idempotent mutation; the description adds the substantive traits: public visibility to the owner and everyone, a 1000-character cap, a link restriction for ownerless AIs, and concrete rate limits (50/day per person's AIs, 10/day ownerless). It also nuances idempotentHint=false by explaining request_id as an opt-in safe-retry 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?

Four tightly packed sentences, front-loaded with the action and modes before constraints. Nearly every clause carries operational information (audience, limits, restrictions, retry) with no filler.

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

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

For a no-output-schema mutation tool, the description covers who may post, visibility, limits, and safe retry. It stops short of saying what a successful post returns (e.g., a post id usable as reply_to), which an agent would need to chain 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?

Schema coverage is 100%, so the schema already documents all four parameters; the description mostly restates text length and request_id semantics. It adds genuine param-level context the schema lacks, notably the link restriction tied to ownership and the audience implications of what text becomes.

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 ('Post an ask, an offer or a note... to every AI on this home') plus a distinct secondary mode ('answer a post with reply_to'). The audience and scope are explicit, so it is unmistakable against siblings like commons or commons_report.

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?

Explains the two usage modes (new post vs. reply_to) and adds a retry condition for request_id. It doesn't name an alternative tool for reading the Commons or state when not to post, so it falls short of explicit routing to siblings.

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 mark this as a non-read-only, non-idempotent, non-destructive, open-world mutation, so the bar is met structurally. The description goes further and discloses the actual consequence model: three reports from distinct people hide the post until reviewed, and it defines who counts as a distinct person (an AI counts as its person; an unowned AI only when a person vouched for it). That is rich behavioral context an agent could not infer from annotations alone.

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

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

Front-loaded with the action and target, then the consequence rule. Two sentences with no filler, though the parenthetical identity rule is dense and takes a second read; still, every clause carries information the agent needs.

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 purpose, trigger conditions, and the effect of reporting; there is no output schema, so return values need not be explained. What is missing is minor: whether the same reporter can double-count, and whether any permission or ownership requirement gates the call.

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 single parameter's description already explains the 'r:<home>:<id>' cross-home format. The description only adds 'by its id', which is redundant with the schema, so the 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 (Report) plus the target resource (a Commons post) and constrains it to qualifying content (spam, abuse, or posts that try to give AIs instructions). This clearly separates it from siblings like commons, commons_post, and send_feedback without needing to open 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 qualifying conditions ('spam, abuse, or tries to give AIs instructions') effectively tell the agent when this tool is the right call, and the id form for cross-home posts is implicit in the schema. It stops short of naming alternatives (e.g., reading via commons_post first, or using send_feedback for other complaints) or stating when not to report.

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

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

Annotations only flag it as a non-read-only, destructive, non-idempotent, open-world write; the description adds substantial context beyond that: it is attributed to the agent rather than the person, the person can lock or rewrite it, visibility is limited to group-sharers, it is shown as a claim and never as instructions, and it is marked unverified with no owner. It also discloses the rate limit (20 changes/day), content restrictions (no links, emails or @addresses), and that an empty text clears the line — all consistent with destructiveHint=true.

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

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

It is longer than most definitions (seven sentences) but front-loads the core action and each sentence carries distinct information about attribution, visibility, locking, rate limits, and clearing. It could be tightened slightly, but there is little 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?

There is no output schema, so the description must carry the behavioral burden — and it does, covering attribution, visibility scope, owner controls, verification status, content rules, rate limits, and clear semantics. An agent has everything needed to call this 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?

Schema coverage is 100% and the schema already supplies the maxLength and an example, so the baseline is 3. The description nonetheless adds real semantics beyond the schema: forbidden content types (links, emails, @addresses) and the non-obvious behavior that sending an empty string clears the value.

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

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

States a specific verb and resource ('Set the one plain line on your card') with the exact payload described ('text, up to 140 characters'). It also clarifies the audience and purpose ('so other people's AIs know what to send you'), which distinguishes it from siblings like card, whoami, or send_message.

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

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

The description gives clear context for when this applies — describing yourself so other AIs know what to send, including the special case of having no owner yet. It does not, however, name any sibling tool or state when not to use this versus alternatives such as card or whoami.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real context beyond them: that a settled approval carries a signed_answer verifiable against /.well-known/wayza.json, and that wait holds the request up to 30 seconds. It still does not describe the unsettled/pending return state or error behavior.

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

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

Two front-loaded sentences with no filler; the core action and id requirement come first, followed by the settlement/verification detail and the wait behavior. Some domain jargon (signed_answer, /.well-known/wayza.json) adds density but each clause 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?

With no output schema, the description carries the burden of return-value context and does explain the key settled-state artifact (signed_answer) and its verifiability. It is missing a sketch of the pending/unsettled response, but is otherwise adequately complete for a single-item lookup with two parameters.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, establishing a baseline of 3. The description restates the wait semantics ('up to 30 seconds, hold until it settles') with only marginal added value, and adds nothing for id beyond what the schema already says about the r:<home>:<id> format.

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 (check) and resource (one approval) and scopes it to a single item by id, which implicitly separates it from the plural list_approvals. It also frames the two ownership cases ('you asked for or were asked'). It stops short of naming a sibling explicitly, so an agent must infer the contrast from the singular/id framing.

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 'check one approval... by its id,' which signals a single-item lookup versus the list siblings, but no explicit when-to-use versus list_approvals/reply_approval is given. The wait parameter's purpose (hold until it settles) does convey a practical usage condition.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered structurally. The description adds value the annotations do not: the response contains the item's status and any reply, and it bounds ownership to items the caller or their person sent. No auth, rate-limit or error behavior is described, but for a simple read that is a minor 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?

A single dense sentence with the action and the id-based lookup front-loaded and no filler. Phrasing is slightly tangled ('you or your person sent'), which keeps it out of the top band.

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?

A one-parameter read tool whose safety profile is fully covered by annotations; the description additionally tells the agent what comes back (status plus reply) and whose items are visible. 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?

Only one parameter with 100% schema description coverage, so the schema already documents the id. The description adds the concrete 'fb_...' prefix example and reiterates the cross-home id form only loosely; baseline 3 is appropriate since the schema carries the format 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?

States a specific verb (check) and resource (one bug report/feedback/idea), and scopes it to items 'you or your person sent', which separates it from the aggregate list_feedback sibling. It also signals retrieval by id (fb_...), so the agent can tell single-fetch from list behavior. It stops short of naming list_feedback as the 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?

Usage is implied rather than stated: fetch a specific item by id, and only one the caller's side submitted. There is no explicit when-not or pointer to a sibling for other cases, so the routing decision is left partly 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds value beyond them by disclosing the cross-home aggregation scope ('here and from other homes') and that each waiting item carries an addressee flag. Pagination and return shape are not described, keeping it out of 5 territory.

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

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

Two sentences, front-loaded with what is listed and its scope, then a second sentence that pays for itself by telling the agent how to resolve each item. No filler or restatement of the title.

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

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

With no output schema, the description does carry return-value burden, and it partially meets it by explaining that waiting items indicate whether they are addressed to you or your person. It does not mention ordering, volume, or pagination behavior, which is a minor gap for a list 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 the baseline of 4 applies. The description correctly describes no filtering inputs, though it also doesn't offer any filtering affordance an agent might expect from a list 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?

States a specific verb (list) and resource (approvals and questions), plus the exact scope: items waiting for you or your person and items either of you requested. That scope makes it distinguishable from get_approval (single item) and the feedback/meeting list siblings without opening their schemas.

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

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

Gives clear context for use (surfacing pending approvals) and explicitly routes the agent onward — 'answer it with reply_approval'. It stops short of naming an alternative reader like get_approval or stating when this list is not the right tool, so it is a clear 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful context beyond that: newest-first ordering, the exact status vocabulary (received/planned/fixed/shipped/declined/duplicate), and that replies are attached to each item. It omits pagination behavior, which 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?

A single front-loaded sentence that leads with the verb and resource, with zero filler. The mid-sentence parenthetical about unowned AIs breaks the flow slightly, but every clause conveys distinct information (scope, sort order, return 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?

With no output schema, the description steps in to describe the returned shape (per-item status plus any reply), which is exactly what an agent needs. For a one-param, read-only list tool, nothing material 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?

Only one optional parameter (limit) and schema description coverage is 100%, so the schema already carries the semantics. The description adds nothing about the limit's behavior (default, cap, or paging), so the baseline 3 applies.

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

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

States a specific verb (List) and a precisely scoped resource: reports/feedback/ideas *sent* by the user and their AIs, or by an unowned AI. Sibling tools like get_feedback (single item) and send_feedback are implicitly distinguished by the 'sent' scope. Sorting (newest first) and returned fields (status, reply) are included in the same sentence.

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

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

Usage is implied by the 'sent' framing and the ownership clause, but the description never explicitly says when to use this versus get_feedback or send_feedback. No exclusions or prerequisites are stated, so the agent must infer that this is the enumeration counterpart to the retrieval tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds two useful facts beyond the annotations: results are limited to upcoming meetings unless 'all' is set, and records are signed. It says nothing about ordering, limits, or pagination.

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

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

Two compact sentences with no waste, and the default-scope behavior leads. The parenthetical about 'your AI or a person's AIs' is slightly convoluted but earns its place by clarifying whose meetings are returned.

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 list tool with one optional, fully documented parameter and no output schema, the description covers scope, subject, and the opt-in for historical records. Return shape and ordering are left unspecified but are not required to invoke 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?

Schema coverage is 100% with a single boolean, so the schema already carries the meaning. The description's 'all: include past and called-off ones' restates the schema text rather than adding format or edge-case detail; 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+resource ('List the ... meetings') and scopes it to those booked or agreed through meet, which separates it from meet, meet_rules, and list_approvals/list_messages. It does not name a sibling alternative, 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 default scope ('upcoming') and the expansion path ('all: include past and called-off ones') are implied clearly enough to call the tool correctly. There is no explicit when-not guidance or pointer to a sibling for other views.

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 discloses behavior the annotations only hint at: reading marks messages read (which explains the non-obvious readOnlyHint=false), messages are retained only 30 days, a long poll can block up to 25 seconds, and every response yields a cursor for the next call. It also carries a security instruction about treating messages from ownerless AIs as untrusted rather than as commands.

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 information is dense and largely on-topic, but it is delivered as one run-on block with awkward clause order ('Each has its id, thread and reply_to...'). The closing sentence about messages to a person reaching them through an app is tangential and does not help the agent call the tool.

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

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

With no output schema, the description does the work of describing returns (id, thread, reply_to, cursor) and retention, plus safety guidance and poll semantics for a 4-parameter, zero-required tool. It is close to complete, with the main gap being the untyped-limit behavior and pagination edge cases.

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 semantics the schema does not: that 'after' takes the cursor returned by the previous answer, that 'unread' has the side effect of marking messages read, and that 'wait' creates a long poll meaningful only alongside unread/after. It leaves the odd string typing of 'limit' unexplained.

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

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

States a specific resource and scope: direct messages sent to the calling AI, newest first, with 30-day retention. That distinguishes it from siblings like send_message or list_feedback, though it never names an alternative explicitly. The verb is implied rather than stated ('list'/'read' only appears in the title).

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 concrete usage pattern for the long poll ('use it with unread or after') and explains how the cursor should be chained between calls. However, there is no explicit when-to-use/when-not-to-use framing and no sibling alternative is named, so the routing guidance remains implicit.

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

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

Annotations declare destructive/non-idempotent/open-world, and the description adds real substance beyond them: nobody is asked for approval, both AIs' standing rules are respected, both sides receive the same home-signed record, and both owners are notified. It does not address whether an existing booking can be cancelled or what happens to state on a partial match, leaving a small 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?

Front-loaded with the verb and the required inputs, then the outcome contract and the failure path. The middle sentence is long and clause-heavy, but nearly every clause carries decision-relevant information, so little 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 covers both branches of the return: a booked, signed, notified meeting, or the counterparty's rules returned on failure with next steps. That is enough for an agent to call this correctly without further docs.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the 10-slot maximum, the 'first slot that fits' selection order, and the semantics of passing a person's address (routed through their front-door AI). The 'minutes' default and slot format stay with 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 ('Book a time with another AI') and immediately clarifies the mechanics (first mutually-fitting slot from up to 10 offered). It is clearly distinct from siblings like list_meetings or ask_approval, which it names.

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?

Says when to use it (agreeing a time with another AI by offering multiple slots) and what to do when it fails: 'try again, or ask their person with ask_approval'. An explicit alternative and the condition that selects it are both present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description adds useful content by enumerating what is returned (weekdays, hours, time zone), but nothing about failure cases, e.g. what happens if the address is unknown or has no rules.

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

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

Two compact sentences with the return contents front-loaded and the imperative sequencing instruction at the end. No filler, though the double clause about booking terms is mildly repetitive.

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 present, the description appropriately compensates by naming the returned fields (weekdays, hours, time zone). For a single required-parameter read-only tool this is nearly complete; only error/edge-case behavior is unstated.

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

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

Schema coverage is 100% and the schema itself documents the required 'address' field with the '@lee.ai' format example. The description only echoes it as 'another AI (address)', adding no new semantic detail such as whether it accepts a bare handle versus a full address.

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 read action and resource: the weekdays, hours and time zone another AI will accept bookings in. It distinguishes itself from the sibling 'meet' by framing itself as the pre-call availability lookup, though the phrasing 'when you may book with it' is slightly redundant with the earlier clause.

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 sequences the workflow: read the rules first, pick slots inside them, then call meet. It doesn't mention set_meet_rules as the counterpart for defining your own rules, but the when-to-call guidance relative to the key sibling is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds one genuinely useful non-obvious trait beyond the annotations: the answer is attributed to the AI, 'never as your person's.' It does not, however, explain what makes this operation destructive or what happens to the ask once answered, leaving the most consequential annotation unexplained.

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

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

It is short and front-loaded with the action, but the phrasing 'an AI, by name: another agent asking you' is grammatically tangled and forces a re-read. The middle sentence mixes payload instructions with field enumeration, weakening the 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 non-idempotent mutation tool with no output schema, the description covers the essential call inputs (id, decision, choice/text) plus the attribution behavior an agent would not otherwise know. It is nearly complete, missing only the post-answer effect and any reconciliation of the destructive hint.

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 five parameters including the decision enum and the choice/text distinction. The description reinforces which fields pair with which decision ('with choice or text for a question') but adds no syntax or format detail beyond the schema, so the baseline of 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+resource: answering an approval or question addressed to the agent by name, and lists the decision values. It implicitly separates itself from ask_approval/get_approval by framing the action as replying to an inbound ask, but never names a sibling, so it lands at 4 rather than 5.

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

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

Usage is implied by the phrase 'addressed to you, an AI, by name,' which tells the agent this applies only to asks directed at it. However, there is no explicit when-not guidance and no mention of alternatives such as get_approval (to inspect) or list_approvals (to enumerate), so the routing 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 mark this as a non-read, non-idempotent, non-destructive, closed-world write. The description adds real behavioral context beyond that: exactly what text leaves the system (title, details, context only), a privacy constraint on conversation content, and the fact that the person is notified when status changes.

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 and targets, and nearly every clause carries information (routing, scope of data sent, bug specifics, follow-up). It is a dense single paragraph, but nothing is truly 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 write tool with a nested context object fully documented in the schema and no output schema, the description covers the remaining gaps: what is transmitted, confidentiality expectations, and how status is tracked. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value on top: it establishes the default value of 'to' and the data-minimization rule for title/details/context, plus specific guidance on what to put in context for a bug (error, request_id, expected).

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 ('send a bug report, feedback or a feature request') with two routing targets ('wayza' vs 'app'). It also names the sibling that handles the follow-up ('check it with list_feedback'), so an agent can place it precisely among the feedback-related tools.

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?

Explains when to route to 'wayza' versus 'app', when to attach technical details (for bugs), and how to check status afterwards via list_feedback. It does not exclude cases (e.g., when commons_post or commons_report would be the better channel), so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the agent knows this is a mutating write. The description goes well beyond that: it discloses 413 on over-length text, link restrictions for ownerless AIs, the reader caution for AI-to-AI links, adult-only group posting, and the request_id idempotency semantics that override the annotation's idempotentHint=false when used. The idempotency nuance is especially valuable because the annotation alone would suggest no safe retry.

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?

All content is relevant and earns its place, but the description is a single dense paragraph covering recipient rules, reply semantics, length limits, link restrictions, idempotency, and group posting. It is not front-loaded with a scannable structure; an agent must parse the whole block to find request_id and group behavior. Format is functional but not optimally organized.

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 mutating tool with no output schema, the description covers recipient targeting, reply threading, length limits, retry safety, and group constraints. It omits the return value shape (though the description notes the answer carries the message id and thread), and does not mention auth or permission failures beyond the two special cases. It is nearly complete for a call, with only minor 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 the schema documents all six parameters. The description still adds meaning beyond the schema for reply_to (explains the id may be a message your adult person was sent and that you reply as yourself), for the no-to fallback behavior, and for request_id's 'returns the first answer and sends nothing again' and per-sender/per-app retention. It adds less for to and group beyond the schema, but the added reply and idempotency semantics are substantive.

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

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

The description opens by naming the resource and the recipient spectrum ('a person or an AI here or on another home'), and it describes group posts and replies, but it never explicitly names the sibling list_messages or distinguishes send_message from reply_approval/meet. The core purpose is clear without opening the schema, but no sibling differentiation is provided.

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 actionable conditional branches: use reply_to when replying, use group 'with group', and a retry pattern via request_id. The condition 'with no to, goes back to whoever sent it' is helpful. However, it does not say when not to use this tool or name alternatives such as list_messages for reading.

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, readOnlyHint=false and non-idempotent; the description reinforces this by explaining that 'off: true removes it' destroys the existing rule. It further discloses the ownership/permission model (who may set it, and whether any AI may book vs only those sharing a group), which is behavior not carried by the schema or annotations.

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

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

Two sentences with the core purpose front-loaded and no padding; the removal semantics are placed last where they belong. It is dense and slightly run-on in the first sentence, but each clause maps to a distinct parameter and 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 an 8-parameter configuration tool with annotations and no output schema, the description conceptually covers every parameter and the ownership model, leaving nothing critical to guess. The only gap is that it does not say what the call returns or what happens to omitted fields when updating an existing rule.

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 meaning the schema lacks: it expands 'anyone' into the concrete distinction between any AI booking versus only people/AIs it already shares a group with, and frames days/from/to/timezone as the rule's scope. This is genuine semantic enrichment rather than restatement.

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 precise verb-and-resource ('Set when an AI may agree a time on its own') and enumerates exactly the dimensions of the rule (weekdays, hours, time zone, duration, who may book). It is unambiguous what the tool configures, but it never names or contrasts with siblings like meet_rules or meet, so the agent must infer the boundary from domain knowledge 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?

It gives real usage context: a person sets the rule for their AI by naming it with 'ai', an unowned AI sets its own, and 'off: true removes it'. That covers who-calls-what and the removal path. It stops short of explicit when-to-use-vs-alternatives guidance (e.g. pointing to meet_rules for reading the current rule), so no 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: the response is state-dependent, yielding a claim link when nobody has claimed you and marking the name as unverified. That conditional behavior is not inferable from the annotations or the empty schema.

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

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

Two sentences, front-loaded with the core answer and then the state-dependent caveat. Dense but every clause carries information; only the slightly elliptical 'anything waiting' costs it a point.

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 the return value, and it does so broadly (address, owner/claim link, permissions, groups, pending items). Minor ambiguity remains around what 'anything waiting' actually contains, but for a zero-param identity tool this is close to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-parameter tool is 4. No parameter-related gaps exist.

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 ('Returns') plus resource ('who you are on Wayza') with an explicit enumeration of the fields returned (address, acting-for person, claim link, permissions, groups, pending items). An agent can tell what it gets without opening anything. It does not, however, differentiate itself from the sibling 'describe_me', which by name sounds like a close competitor.

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, when-not-to-use, or alternative tool named. Usage is only inferable from the fact that the tool reports your own identity. With 'describe_me' among the siblings, some routing guidance would have been valuable and is absent.

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