Noemic

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

Annotations are all false, providing no safety hints. The description adds important behavioral guidance: show only signInUrl, keep requestId and pollSecret private, and never ask for credentials in chat. These are critical operational constraints beyond what annotations convey.

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 only two sentences: the first states the purpose, the second gives essential privacy rules. Every sentence earns its place, and important information is front-loaded. 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?

Given its simplicity (0 params, no output schema), the description covers the purpose and critical behavioral constraints. It could mention the exact response structure, but the privacy rules imply the fields returned, and sibling tools like finish_sign_in likely handle follow-up. It is sufficiently complete for an AI to use 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 tool has zero parameters, so the baseline is 4. The description doesn't need to add parameter details since none exist. It mentions the relevant output fields (signInUrl, requestId, pollSecret) in the privacy instructions, adding context about what the tool produces.

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 starts the browser handoff, specifies its purpose (personalized network reads or saving an unpublished bet draft), and implicitly differentiates from the sibling finish_sign_in. The verb 'Start' and resource 'browser handoff' are specific 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 clear context for when the tool is needed ('required for personalized network reads or saving an unpublished bet draft'). It does not explicitly name alternatives or exclusions, but the sibling list naturally implies other tools handle different functions, so no exclusions are necessary.

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?

Description says 'Public, read-only explanation' and adds context about no-custody boundaries and content coverage. Annotations already flag readOnlyHint=true and destructiveHint=false, but 'public' and the explanation scope add useful behavioral context beyond 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, front-loaded with the core purpose and then explicit usage guidance. No wasted words or repetition of schema/annotation details.

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 zero-parameter explanation tool, the description fully covers what it does and when to call it. No output schema exists, but the description's clarity is sufficient for correct selection and 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 tool has zero parameters, so parameter semantics are not applicable. The description still adds value by explaining what the tool does, earning the baseline of 4 for no-parameter tools.

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 explains Noemic, its trust boundaries, and key concepts like source provenance and custody. This distinguishes it from sibling tools that perform actions like signing in or proposing bets.

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 states when to use it: when a person asks what Noemic is, why it can be trusted, or how matching works. It does not mention when not to use it or alternatives, but the sibling tools are clearly different operations.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world. The description adds meaningful behavioral context: results cite only scope-authorized evidence and weak results are clearly labeled. This goes beyond the annotations without contradicting them, though it stops short of detailing result structure or failure modes.

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

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

Two sentences, front-loaded with purpose, then usage guidance, then behavioral caveats. No filler or repetition; every clause adds value. This is exemplary conciseness for a tool description.

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 tool's moderate complexity (5 params, no output schema), the description covers purpose, usage exclusions, and key behavioral traits. It does not explain return format or error conditions, but the read-only nature and annotations reduce the need. Largely complete for an AI agent's selection and 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?

Schema coverage is 60% (3 of 5 params described). The description adds semantics for offerId by mentioning 'optionally anchored to an existing draft offer,' which clarifies that parameter. However, 'limit' remains undocumented in both schema and description, and no extra meaning is provided for explicitUserRequest beyond its const:true schema constraint. The description partially compensates but not fully.

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 ('find') and resource ('counterparties' — people for concrete falsifiable forecasts or disagreements), and explicitly distinguishes itself from sibling tools by labeling it 'Secondary' and contrasting with open bets/useful questions. This clearly differentiates from find_relevant_bets and propose_bet.

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 states when to use: when the user asks to find a person for a concrete forecast/disagreement, optionally anchored to an offer. Also provides a strong when-not: 'Do not call proactively' and directs to open bets/useful questions instead. This is clear usage guidance with alternative tools in mind.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses the shouldSurface behavior, the distinction between model-initiated and direct user search, and the privacy constraint that it does not scan background chats. No contradictions with annotations; it adds meaningful behavioral context.

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

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

The description is front-loaded with the core purpose and contains four concise sentences, each providing essential operational or behavioral guidance. There is no wasted text; 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?

Given the absence of an output schema, the description provides crucial return behavior (shouldSurface, offers) and usage constraints. It covers the proactive vs. explicit user request distinction, privacy, and how to handle weak results, making it sufficiently complete for an agent to use 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 description coverage is 75%, with descriptions for sessionToken, conversationContext, and explicitUserRequest. The description adds value by elaborating on conversationContext ('Pass only relevant current-conversation context') and hinting at explicitUserRequest via 'direct user search.' However, the limit parameter lacks a description, and the description does not fully compensate for that gap.

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 function: 'Read-only ranking of open BetOffers for the signed-in user.' This specifies the verb (ranking), resource (open BetOffers), and scope (signed-in user), distinguishing it from sibling tools like propose_bet and find_counterparties.

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 guidance on when to use the tool: proactively when the conversation contains a 'concrete falsifiable forecast, measurable disagreement, or explicit desire to bet.' It also instructs to pass only relevant context, notes that the tool does not scan chats, and explains how to handle weak relevance (do not mention Noemic or interrupt).

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 behavioral context beyond annotations by explaining that a 'pending' result means the user hasn't approved, and a 'complete' result yields a private sessionToken. It also warns to never expose the secrets, adding security-relevant 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 three concise sentences, front-loaded with the action, and includes a necessary security warning. Every sentence earns its place 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 no output schema, the description covers the main outcomes (pending/complete) and the returned sessionToken, which is adequate for a sign-in completion tool. It doesn't discuss error cases, but the core context is sufficiently 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?

With 0% schema description coverage, the description compensates by identifying both parameters (requestId, pollSecret) and indicating they are private secrets exchanged in the process. It doesn't detail each parameter individually but adds meaning beyond the bare schema.

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

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

The description clearly states the tool's function: exchanging private requestId and pollSecret to complete a sign-in. It specifies the resources involved and the action, distinguishing it from sibling tools like begin_sign_in.

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 explicitly states the tool should be used 'after browser approval' and explains the pending vs. complete outcomes, guiding when to call. It doesn't explicitly name alternatives, but the sign-in flow context makes the usage 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 critical non-effects: 'never publishes, invites, accepts, charges, escrows, or binds anyone.' It also warns against inventing source IDs or quotes, going beyond the basic readOnlyHint=false annotation. This is valuable behavioral context.

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

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

Three sentences with no filler. The main action, usage trigger, and key constraints are all front-loaded and concise.

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 12 parameters and no output schema, the description covers the core purpose, when to use, and non-effects. The schema carries parameter details. A minor gap is that the description does not mention what the call returns or how success is signaled, but the overall context is strong.

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 92%, so the schema already explains most parameters. The description's mention of sourceRecordId constraints ('never invent an ID') is already present in the schema, and no other parameter-level details are added.

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 'Create an unpublished draft,' a clear verb+resource pair. It distinguishes itself from sibling tools by specifying it formalizes a falsifiable forecast or disagreement, not a search or auth operation.

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 states when to use: 'when the user wants to formalize a concrete falsifiable forecast or disagreement.' It also gives a negative directive: 'must not silently persist a passing remark.' While no alternatives are named, the sibling tools are clearly unrelated, so the guidance is unambiguous.

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