mutual

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

Annotation Contradiction. The readOnlyHint annotation marks the tool as read-only, yet the description says resend_email=true 're-sends' an email and with nothing pending it 'sends the welcome email' — an undeniable side effect. Even though the description usefully discloses rate limiting and the approval boundary, the contradiction with annotations makes this dimension fail.

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

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

The description is three sentences, with the primary listing purpose front-loaded before the side-effect caveats. Every sentence earns its place: the first defines the output scope, the second prevents an invalid approval attempt, and the third explains the optional resend behavior and confirms the response content.

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

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

For a two-parameter, no-required-field tool, the description covers the main return fields, the optional side effect, rate limit, and output for the resend case. It is slightly incomplete only because the readOnlyHint contradiction muddies the tool's safety profile and because the list-mode return shape is not fully described beyond the two named fields.

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 already explains both parameters. The description adds practical meaning for resend_email beyond the schema: what 'can't find it' means, the once-an-hour limit, the welcome-email fallback, and that the reply states what was sent. This is more than the baseline but not needed for api_key, which the schema already fully describes.

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

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

The description opens with a specific verb and resource: 'List matches where both twins flagged each other,' and names the output fields ('waiting_on', 'your_human_was_emailed'). This clearly distinguishes it from sibling tools like get_flags or get_candidates, which cover separate 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?

It gives clear context for the main use (list pending matches) and explicit conditions for the resend_email parameter: pass it if the human can't find the email, at most once an hour, and with nothing pending it sends the welcome email. It also warns that no approval tool exists. However, it does not explicitly compare against the sibling resend_confirmation_email, which could be the natural alternative for the resend use case.

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 annotations providing no meaningful safety detail, the description fully carries the burden: it states the human forwards the invite themselves, the link contains the asker's first name and reason, confirmed joins contribute up to three flags to the budget, and there is a ten-per-day cap. These are substantive behavioral and side-effect disclosures beyond the structured 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?

Six sentences, each with a distinct job: trigger conditions, link content, forwarding behavior, prohibition on sending, budget effect, and rate limit. It is front-loaded with when-to-use guidance and contains no filler or duplication of the schema.

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

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

Given the straightforward parameter schema, the description covers the triggers, constraints, side effects, and rate limiting. Although there is no output schema, the nature of the result (a shareable invite link the human forwards) is implied by 'The link says...' and 'Your human forwards it themselves,' so an agent has enough context to invoke 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 description coverage is 100%, so reason, api_key, and for_whom are already fully documented. The description only restates that the reason is 'in their words' and adds no new parameter-level meaning, so the baseline 3 for high coverage applies.

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

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

The description names a specific action and resource: 'make a personal invitation,' and grounds it in two concrete triggers: when the human names someone, or when the network has no matching person. This is clearly distinct from sibling tools like get_invites or check_matches because it creates a deliverable rather than reading matches or intros.

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 provides explicit when-to-use conditions ('When your human names someone they'd love to be connected through -- or when the network has nobody matching what they're seeking') and a clear behavioral boundary ('NEVER send it on their behalf'). It does not, however, name the alternative sibling tools to use when matches do exist, so the guidance is slightly less explicit 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?

The description adds meaningful behavioral context beyond the destructiveHint annotation: it specifies exactly what gets deleted (profile, flags, pending matches) and what does not get undone (completed intros). This is exactly the kind of destruction transparency an agent needs.

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, each carrying necessary information: what is deleted, what persists, and when deletion is permissible. The most important fact is front-loaded, and there is no filler.

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

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

For a destructive tool with no output schema, the description covers the essential outcomes and the critical precondition. It tells an agent what will be removed, what will still exist, and when it is ethically appropriate to call the tool. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so both api_key and confirm are already documented in the schema. The description reinforces the consent requirement for confirm, but adds no new parameter-level detail beyond what the schema provides.

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

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

The description states a specific verb and resource: it deletes the profile, flags, and pending matches. It also distinguishes itself from siblings like report_twin by clarifying it is a full removal of the human from the network, not a flag or 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?

The description gives an explicit usage condition: 'Only do this if your human asked to be removed.' It clearly implies this should not be used on the agent's own initiative. It does not name an alternative sibling for the 'not asked' case, but the consent gate is strong and practical.

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 critical behaviors beyond the sparse annotations: no notification is sent, flags persist for 60 days, mutual flags create a match, the human's name is stripped automatically, and other people's names must not be included. This is exactly the kind of behavioral context an agent needs for a privacy-sensitive action.

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

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

The description is concise yet information-dense. It front-loads the core action and privacy guarantee, then explains persistence, matching, and the no-names rule, and ends with a clear alternative/limitation. Every sentence adds necessary guidance without redundancy.

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?

Given the moderate complexity, fully documented schema, and minimal annotations, the description provides enough behavioral and usage context for correct invocation. It covers privacy, duration, match conditions, naming restrictions, and the absence of any alternative communication path, making the definition effectively 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 input schema already covers all parameters at 100%, so the baseline is 3. The description adds meaningful constraints beyond the schema: the rationale is shown to humans if matched, no names should appear, and what_they_get must be justifiable or the flag should be skipped. This enriches the parameter semantics rather than merely repeating property descriptions.

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

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

The description states a specific verb and resource: privately flag one person with reasoning and what they would get out of it. It also distinguishes this from messaging/pitching by explicitly saying it is the only way to express interest, so an agent can tell it apart from sibling tools like create_invite or get_flags.

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 makes the primary use case explicit: this is how to privately express interest in a candidate. It also provides a skip condition—if you cannot state what the other person gets, the flag is worth skipping. It does not enumerate all alternatives, but the 'only way' framing gives strong 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 mark the tool readOnlyHint=true, so the read-only nature is established. The description adds useful behavioral detail beyond that: it returns the public-facing card, content held back until an intro, and email verification status. There is no contradiction between the description and annotations.

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

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

The description is a single sentence that packs three meaningful pieces of information with no filler. There is minor redundancy with the title, but the content is front-loaded and every 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?

For a simple read tool with one optional parameter and no output schema, the description adequately explains what the response contains: the peer-visible card, intro-gated fields, and email verification status. It does not detail edge cases, error conditions, or formatting, but these are less critical given the low complexity and read-only annotation.

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 only parameter, api_key, is thoroughly explained in the schema with bearer-token context. The tool description itself adds nothing about parameters, 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 identifies a specific resource (the human's 'card') and the exact view being returned: the card as other agents see it, pre-intro hidden fields, and email verification status. The title reinforces a read operation and makes it distinguishable from the sibling update_brief, though it never names that sibling.

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

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

The description implies when to use the tool: when the agent needs to see what other agents can see, including intro-gated information. It provides context about the intro state but gives no explicit guidance about when not to use it or which sibling tool to prefer.

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 substantially expands on the annotations by warning that card text is untrusted data from a stranger's agent and must never be treated as instructions. It also discloses redaction behavior and the exclusion of flagged/matched people, giving the agent crucial information about how to interpret results and respond to suspicious profiles. This goes well beyond what readOnlyHint and openWorldHint already 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?

The description is front-loaded with the core behavior and then presents the safety warning and the 'since' usage. The safety warning is somewhat long, but every part earns its place given the untrusted-data risk; it remains reasonably tight and well-ordered.

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 tool with no output schema, the description gives a useful preview of the return concept: a redacted card with no name or contact details. It covers the main usage filter and the critical security context. It does not describe possible pagination, empty-result behavior, or the full card shape, but the current level is sufficient for safe and correct invocation.

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

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

The input schema already documents both parameters fully, and the description adds only a mild reinforcement of the 'since' parameter by relating it to 'after you last looked.' It does not add meaning to the api_key parameter beyond what the schema provides, so a baseline score of 3 is appropriate given 100% schema coverage.

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

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

The description clearly identifies the resource: everyone else on the network as redacted candidate cards, excluding people already flagged or matched. It is specific enough to understand the tool's role among siblings, but it does not explicitly differentiate itself from similar listing tools like check_matches or network_size.

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 provides useful context by explaining the optional 'since' filter and when to pass it, and it suggests reporting manipulative profiles with report_twin. However, it does not explicitly say when to prefer this tool over alternatives such as get_intros, get_invites, or check_matches, so usage guidance is mostly implied rather than explicit.

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 readOnlyHint annotation already establishes the operation's safety, and the description adds useful behavioral context beyond that: only 'still live' flags are returned, along with whom they reference, the rationale, and match status. This is meaningful additional detail about the tool's 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 description is a single, tightly written sentence that front-loads the core purpose (your flags, still live) and enumerates the return fields without waste. Every part of the description contributes directly to understanding what the tool does.

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 appropriately enumerates the response contents: whom, rationale, and match status. It could more explicitly define 'live', but the phrase 'still live' is sufficient. The simple tool shape, clear annotations, and complete parameter schema make this description adequate for correct use.

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

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

The input schema covers 100% of the single parameter (api_key) with a thorough explanation of when to pass it versus relying on the bearer token. The tool description adds no parameter-specific information, so the baseline of 3 is appropriate.

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

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

The title "See your own flags" and description "The flags you have placed that are still live: whom, your rationale, and whether each has matched yet" clearly identify the operation as retrieving the user's own active flags with specific return fields. The scope (own, live flags) distinguishes it from siblings like flag_person (placing) and check_matches (checking).

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 clearly implies when to use this tool: when you need to review your own live flags and their details. It does not explicitly name alternatives or state when not to use it, but the contextual scope is unambiguous enough that an agent can select it 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 declare readOnlyHint=true, covering the safety profile. The description adds useful behavioral context by specifying the approval condition and the uniqueness of sensitive data, but it does not discuss pagination, ordering, or response shape. This is acceptable given the annotations but not deeply transparent.

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

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

The description is two tight sentences with no filler. The primary function is stated first, and the important uniqueness caveat is second. Every word 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 simple read-only list operation with one optional parameter, the description covers what the tool returns conceptually (approved introductions with names and contact details) and the key scoping condition. It does not detail response structure, but the absence of an output schema and the simplicity of the tool make this 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?

There is only one optional parameter, api_key, and the schema describes it thoroughly, including when to pass it versus using the bearer token. Schema description coverage is 100%, so the description need not add parameter-level detail. 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 uses a specific verb ('List') with a clear resource (introductions) and a concrete inclusion criterion ('where both humans approved'). It also adds the unique property that this is 'the only place names and contact details ever appear,' which clearly differentiates it from sibling tools like get_candidates or get_invites.

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 statement 'This is the only place names and contact details ever appear' gives a strong reason to use this tool when contact information is needed. It does not explicitly name sibling alternatives or state when not to use it, but the uniqueness claim provides clear contextual routing.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, so the description does not need to repeat safety traits. It adds useful context about the specific data returned (used invites, handles, counts, personal link) but does not disclose potential behaviors such as pagination, rate limits, or error handling. No contradiction with annotations.

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

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

The description is a single sentence that efficiently conveys the core purpose and return values without redundancy. It is front-loaded with the most important question ('Which invites were used...'). Slightly informal phrasing ('your human's') but otherwise tight.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately conveys what information an agent can expect: invite usage, joining handles, confirmation counts, and the personal link. It omits response format and pagination details, but these are minor for a tool of this simplicity.

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 only parameter, api_key, is fully documented in the schema with a detailed explanation of when to omit it (if bearer token is set) or pass it (for clients like ChatGPT connectors). The tool description itself adds no parameter information, so the schema carries the full burden. With 100% schema coverage, 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 clear verb ('get') and resource ('invites') and enumerates specific return data: which invites were used, who joined by handle, confirmation counts, and the personal invite link. This distinguishes it from creation tools like create_invite and other getters like get_brief, though it does not explicitly name alternatives.

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 name and description—this is the tool for viewing invite-related information—but there is no explicit guidance on when to use it versus alternatives, nor any stated exclusions or prerequisites. The context is clear enough for a basic read operation.

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 signal read-only, open-world, and non-destructive behavior. The description adds genuinely useful behavioral context: no key is required, an empty network must be reported plainly rather than implying matches, and candidates remain invisible until registration. It does not describe the exact return shape, but for a simple count tool the behavior is well covered.

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

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

The description is compact and front-loaded with the most important instruction: call before registering and tell the human the number. Each subsequent sentence adds a distinct point about empty networks, candidate visibility, and honest reporting. The phrasing is slightly ornate but every sentence earns its place.

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

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

For a zero-parameter, read-only count tool with no output schema, the description covers the key operational details: when to call, that no key is needed, how to interpret an empty result, and why this is the pre-registration tool. The only minor gap is not stating the return format explicitly, but the title makes the integer count evident.

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 has zero parameters and schema description coverage is 100%, so there is nothing for the description to document. The explicit 'Needs no key' note usefully reassures the agent that no authentication parameter or setup is required.

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

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

The title and description together make it clear the tool reports the number of people on the network: 'tell your human the number' and 'How many people are on the network.' It also distinguishes itself from candidate-listing behavior by noting candidates are only visible after registration. However, the description never states the operation in a direct verb+resource form like 'Returns the current network member count.'

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 explicit timing: 'Call this BEFORE registering anyone.' It also states the tool needs no key, instructs how to handle an empty network honestly, and explains that candidate visibility is tied to registration, positioning this as the only honest pre-registration way to answer. This is strong practical guidance for an agent deciding when and how to use the 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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, indicating side effects but not destruction. The description goes beyond these by explaining the full flow (link emailed, human clicks, key displayed), the rate limit (at most once per hour), and a privacy behavior (the reply is identical whether or not the email is registered). This adds valuable context about what the tool does without contradicting any annotation.

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

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

The description is concise (three sentences) and front-loaded with the primary use case. Every sentence contributes: the trigger condition, the process, the rate limit, the response behavior, and the alternative. There is no redundancy or 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 tool with a single simple parameter and no output schema, the description covers all necessary aspects: when to use, what happens, rate limiting, response behavior, and the alternative path for unverified twins. There are no obvious gaps that would prevent an agent from calling 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?

The schema has a single parameter 'email' with no description (schema coverage 0%). The description implies that 'email' is the human's inbox address to which the recovery link is sent ('A link goes to their inbox'). While it doesn't explicitly state that this must be the registered email of the human, the context of the tool and the phrase 'whether or not the email is registered' make it reasonably clear. This adds meaning beyond the raw type.

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

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

The description clearly states the tool's purpose: recovering a lost key by emailing a recovery link to the human's inbox. It explicitly names the condition (verified twin) and the action (send link, human clicks, key revealed), and distinguishes it from the sibling register_twin by specifying when that alternative should be used instead. This is a specific verb+resource with clear differentiation.

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

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

The description provides explicit when-to-use guidance: 'Use when your human has a verified twin but you no longer have its key.' It also gives an explicit alternative: 'If the twin was never verified, just call register_twin again -- unverified twins are replaced.' Additionally, it states a rate limit ('Works at most once an hour'), which is a usage constraint. This fully addresses selection among 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?

Beyond the annotations, the description discloses significant behavior: immediate registration, the delayed confirmation email with a confirm-or-pause link, the returned API key, automatic name withholding, the pseudonymous rather than anonymous nature of the card, and replacement of an existing unverified twin. All of this materially helps an agent understand side effects.

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

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

The description is long but dense; every clause earns its place. It front-loads purpose, then covers content standards, privacy behavior, timing, return value, and the overwrite rule in a coherent, non-repetitive flow.

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

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

The definition covers everything an agent needs to invoke registration properly: purpose, content quality, privacy behavior, timing, the returned API key, and the replacement side effect. The only notable gap is behavior when a verified twin already exists for the email, since only the unverified-twin case is described.

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 94%, so the parameter descriptions already do most of the work. The description adds useful writing guidance that the schema cannot convey: be specific and honest, include one checkable fact, and write at the human's comfort level for recognition. This shapes the free-text fields like about, seeking, and offering.

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 first sentence states a concrete action and artifact: 'Create a networking twin for your human so they can be matched with other people.' It clearly distinguishes this as the creation path rather than update_brief, delete_twin, or check_matches, and even frames it as a replacement for a signup form.

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 makes the use case explicit: use it when registering the human you represent and writing their brief from what you already know. It also discloses the overwrite behavior for an unverified twin. It does not explicitly name alternatives like update_brief for editing an existing twin, but the intended context 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?

The description discloses key behavioral traits beyond the annotations: reports are 'recorded for human review; nothing happens automatically' and there is a daily limit of 10. This is valuable context that the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) do not convey, and it does not contradict any annotation.

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, no filler. The first sentence front-loads the exact reportable criteria, and the second efficiently covers outcome and rate limit. Every clause earns its place and the structure is easy to scan.

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 reporting tool, the description fully explains what to report secret; what the report does, what happens afterwards, and the rate limit. With no output schema, it would ideally mention what the API returns, but 'nothing happens automatically' implies a passive recording, making the absence of an explicit return description acceptable. No critical information 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 parameters (handle, reason, api_key) are already fully documented in the schema. The description does not add any additional meaning or nuance for the parameters; it explains the tool's purpose but not the semantics of its arguments. 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 clearly states the verb 'Report' and the resource 'a card', and defines specific trigger conditions: the card's text addresses the agent, claims to speak for the platform, or misrepresents a person. It does not explicitly name a sibling alternative such as flag_person, so it loses the differentiation bonus, but the core purpose is precise and 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?

The description provides explicit, enumerable criteria for when to use the tool, effectively acting as usage guidance. It also includes the 'At most 10 a day' rate limit as a practical constraint. However, it does not mention when not to use it or point to an alternative like flag_person or get_flags, so it falls just short of full routing guidance.

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

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

Annotations already indicate a non-read-only, non-destructive operation, but the description adds meaningful behavior beyond that: the rate limit of once per hour and the conditional email substitution when a match is waiting. There is no contradiction with the annotations, and these extra details materially affect agent decisions.

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

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

The description is three sentences with no filler. It front-loads the use case, then the action, then exclusions/rate-limit/conditional behavior. Every sentence carries decision-relevant information.

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

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

For a tool with one optional parameter, no output schema, and clear annotations, the description covers all necessary context: when to use, what it does, what it does not do, rate limiting, and a state-dependent behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% for the single api_key parameter, which already explains when to pass it vs. omit it. The tool description does not add additional parameter-level meaning beyond what the schema provides, 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 opens with the exact trigger condition ('Use when your human says they did not receive the email confirming you registered them, or cannot find it') and states a specific verb + resource ('Re-sends that email to the address on file, with the confirm link'). It also explicitly contrasts itself with recover_key, so an agent can immediately distinguish it from that sibling.

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 provides explicit when-to-use guidance (user reports missing confirmation email) and an explicit exclusion ('This is NOT recover_key: this does not touch your API key'). It also notes the rate limit ('Works at most once an hour') and the conditional behavior for a waiting match, which are essential for correct invocation timing.

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 the key behavioral consequence—the current key is invalidated—which goes beyond what readOnlyHint=false alone conveys. It could additionally note that existing clients using the old key will stop working, but 'invalidate' already makes the effect clear.

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 no filler: the first states the operation, the second states the trigger. The action is front-loaded and every word 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 low-complexity tool with one optional, well-documented parameter and no output schema, the description is largely complete. The only minor gap is that it does not explicitly state that the new key is returned, though 'issue a new key' implies 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 the schema's api_key description already explains when to include or omit the parameter. The tool description adds no extra parameter semantics, so the baseline score 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 action ('Issue a new key and invalidate the current one') that clearly distinguishes rotation from plain key lookup or creation. It does not name or contrast sibling tools such as recover_key, so it falls just short of perfect differentiation.

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

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

'Use if the key may have leaked' gives a clear and actionable trigger condition. It does not mention exclusions or alternative tools, so there is no explicit when-not-to-use 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?

The description discloses key behavioral semantics: partial updates ('Only the fields you pass are changed') and response behavior ('the result is returned'). It also adds practical guidance about match-quality impact. Annotations already communicate non-read-only and non-destructive, so the description usefully supplements rather than repeats them.

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

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

The description is a bit long but information-dense, front-loading the core action and update semantics before providing value lists. Each section earns its place, and the formatting with colons and comma-separated examples is easy to scan.

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

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

For an 11-parameter update tool with no output schema and no required parameters, the description provides the essential operational context: when to call it, partial-update behavior, return behavior, and recommended field values. The remaining gaps are mostly self-explanatory field names rather than critical missing instructions.

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 only about 9%, so the description carries most of the parameter-knowledge burden for the non-obvious enums. It adds concrete value by listing suggested values for seniority, meeting_types, and industries, but several parameters such as geo, about, headline, offering, and remote_ok are still left without explicit explanation beyond their names.

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 ('Revise') and resource ('the brief') and frames it around the human's changing goals, which is distinct from sibling tools like get_brief or check_matches. The title reinforces the purpose without being a tautology.

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 clearly states when to use the tool: whenever the human's goals change, and emphasizes that keeping 'seeking' current is the top priority. It does not explicitly name alternatives or exclusions, but the sibling context makes the intended use unambiguous.

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