Trust Switchboard

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

With no annotations, the description must disclose side effects and requirements. It does: it runs trust_check, logs pass/fail, returns speak + receipt, and needs a write key. This covers the operation's dependencies and logging side effect, though it does not explain failure behavior or what speak/receipt contain.

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 deliver the core usage rule, behavior, outputs, and a prerequisite. Every clause earns its place and the most important guidance is front-loaded. No filler or repetition.

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

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

The description gives a useful workflow hint but is incomplete for a tool with four undocumented parameters and no output schema. It names return values 'speak + receipt' without explaining their meaning, gives no parameter guidance, and does not clarify failure or edge-case behavior.

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

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

Schema description coverage is 0% and the description provides no explanation of query, action, policy_id, or target_url. It only mentions needing a write key, which is not mapped to any parameter. The description fails to compensate for the fully undocumented schema.

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

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

The description states a specific trigger ('Call BEFORE every recommend') and a concrete behavior: it runs trust_check, logs pass/fail, and returns speak + receipt. This distinguishes it from the sibling trust_check because commit_recommend adds logging and returns extra artifacts, though 'recommend' itself is not in the sibling list and 'speak + receipt' are left undefined.

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 guidance: 'Call BEFORE every recommend.' It also mentions the required write key prerequisite. It does not explicitly say when not to use it or name alternatives, but the 'before every recommend' rule gives a clear usage context.

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 no annotations, the description carries the full burden of disclosing behavior. It does reveal that the tool is public and human-invoked ('Human tap'), which is useful, but it does not disclose side effects, whether the decision changes state, reversibility, or any safety implications.

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

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

The description is short but cryptic. 'Human tap' is jargon rather than clear prose, and the two fragments do not provide enough substance. This is under-specification, not efficient conciseness.

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 2 required parameters, no output schema, and no annotations, the description is severely incomplete. It does not clarify the intended operation, the meaning of the decision values, what happens after approval, or what response to expect.

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 0% and the description adds no meaning to either parameter. It does not mention approval_id, decision, or the significance of the approved/denied enum, leaving the agent to infer semantics solely from parameter 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 'Human tap. Public so the desk can approve without the org key.' is vague about what the tool actually does. It references approving but does not clearly state that this tool decides whether an approval request is approved or denied, and it relies heavily on the tool name and parameter enum for meaning.

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 minimal context about a desk user approving without an org key, but it provides no explicit guidance on when to use this tool versus siblings like request_approve. There is no when-to-use or when-not-to-use direction.

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?

No annotations are present, so the description carries the full burden. It does disclose an important behavioral condition—'Needs a write key'—and indicates the operation is scoped to 'one pond.' However, it does not explain side effects, what 'scoring uniqueness' entails, or the response/failure behavior, leaving significant gaps.

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

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

The description is a single efficient sentence that front-loads the action and includes a necessary access prerequisite. There is no redundancy or filler. The brevity hurts completeness elsewhere but the text as written is well-structured 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 6-parameter tool with no annotations and no output schema, the description is far too sparse. It omits parameter semantics, return values, side effects, and usage conditions. An agent would not be able to invoke this tool correctly based only on this definition.

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 0%, and the description adds almost no parameter meaning. Terms like 'listing' and 'pond' loosely map to name/url and pond, but org_id, summary, and one_liner are entirely unexplained. The description fails to compensate for the undocumented 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 uses a specific verb and resource: 'Ingest a listing and score uniqueness inside one pond.' This clearly conveys the action and context, and is distinct from sibling tools like log_click or commit_recommend. It lacks explicit sibling differentiation, but the action is concrete enough to identify the tool's purpose.

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

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

No guidance is given about when to use this tool instead of sibling tools such as log_intent or request_approve. The only usage-related signal is 'Needs a write key,' which is a prerequisite rather than a usage condition. There are no exclusions, alternatives, or selection criteria.

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 no annotations, the description carries the burden and does disclose that this records a human-initiated click event and that it is public. It does not mention whether duplicate clicks are collapsed, any validation effects, or what the tool returns, though these are less critical for a simple logging 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?

Two short sentences with the core behavior front-loaded and no filler. 'Public.' at the end adds access context without bloating the 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?

The tool is a simple flat-parameter logger with no output schema, so the description is close to adequate, but it leaves the receipt_id relationship ambiguous and provides no parameter-level guidance. For a tool with no annotations, a bit more context about required fields or return behavior would make it fully complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not map the behavior to item_id, item_url, or receipt_id. The parameter names are somewhat self-explanatory, and the receipt context adds meaning, yet the required item_url vs optional receipt_id relationship is left 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?

The description names a specific action (record), a precise event (a human clicked an item), and a contextual qualifier (after a receipt). This distinguishes log_click from the sibling log_intent, which presumably records intent rather than an observed click.

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

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

The phrase 'after a receipt' gives a clear contextual use case, and 'Public' signals an open call, but there is no explicit when-to-use versus alternatives or any exclusion. The distinction from log_intent is implied rather than stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully adds that a write key is required and that a receipt_id is returned, which informs authentication and success behavior. However, it does not disclose side effects, idempotency, failure modes, or whether the logged intent is externally visible.

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 exceptionally concise: three short sentences deliver purpose, a key prerequisite, and the expected return value. Every sentence earns its place, and the main purpose is front-loaded. No filler or redundant wording is present.

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 five parameters, no annotations, and no output schema, the description is too sparse. It covers the write key and return receipt, but omits parameter meanings, when to call, and behavioral details needed for reliable agent selection and invocation. An agent would likely need to guess at several important 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 description coverage is 0%, so the description must compensate for the five undocumented parameters. It does not explain query, action, target_url, result, or policy_id, leaving the agent to infer their meanings purely from names. This is a critical gap for correct invocation.

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 and resource: 'Log that you intend to recommend or act.' This clearly identifies the tool's purpose and distinguishes it from sibling log_click by emphasizing intent rather than the click event. However, 'recommend or act' is somewhat broad and does not explicitly contrast with other sibling 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?

No guidance is given about when to use this tool versus alternatives. The description implies it should be used before recommending or acting, but it does not state when not to use it, mention sibling alternatives, or clarify conditions. The write-key requirement is a prerequisite, not usage context.

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?

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It does not state whether the tool is read-only, whether it has side effects, whether it requires authorization, what happens on failure, or what the output actually contains. 'Stamp' hints at a summary-like result but is not explicit.

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

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

The description is short, but brevity is not clarity. 'Stamp of what it is + last test' is cryptic and under-specified; it does not front-load useful operational information. It reads more like an incomplete note than a tool definition.

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?

Even though the tool has only one parameter and no output schema, the description is far from complete. It fails to explain what the nutrition label represents, what role the URL plays, what the 'last test' refers to, or what the returned result looks like. An agent has too little context to invoke the tool confidently.

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

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

Schema description coverage is 0%, and the description never mentions the required 'url' parameter or explains what URL should be supplied or how it is used. The description provides no semantic value beyond the raw schema, so an agent cannot infer the expected input format or meaning.

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 'Stamp of what it is + last test' is evocative but vague: it suggests the tool produces some kind of label or summary, and the tool name 'nutrition_label' helps slightly. However, it lacks a clear verb, resource, or explicit statement of what action is performed, and it does not distinguish the tool from its siblings.

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

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

The description provides no guidance on when to use this tool versus alternative tools. There is no mention of context, prerequisites, or exclusions, and the sibling tool names do not help clarify selection criteria.

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 no annotations provided, the description carries full behavioral disclosure. It states that the agent blocks/waits, that a human must approve, and that a write key is required. This is meaningful behavioral context beyond a simple 'requests approval' statement.

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

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

The description is very short and contains no filler; each fragment adds a distinct piece of information. It is not structured as a formal definition, but it is appropriately compact for its message.

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 four undocumented parameters, no output schema, and no annotations, the description is incomplete for reliable invocation. It covers the high-level approval flow and auth requirement, but leaves parameter meanings, return behavior, and failure modes unexplained.

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 0%, and the description does not explain any of the four parameters (`query`, `action`, `target_url`, `amount_usd`). The description adds no parameter-level meaning, so agents would have to guess what `action` or `target_url` should contain.

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 communicates a specific behavior: the agent pauses and waits for human approval, which clearly distinguishes it from siblings like decide_approve (which likely means the agent decides). The language is informal but the core action is identifiable.

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

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

The phrase 'HITL pause' implies the tool is for human-in-the-loop approval scenarios, giving some usage context. However, it does not explicitly state when to use this tool over alternatives like decide_approve, nor does it mention exclusion criteria.

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?

Despite having no annotations, the description discloses substantive behavior: the check cannot be overridden, fails closed, and requires a write key. These are important safety and authorization traits beyond what the name alone conveys. It does not describe return behavior or side effects, but the disclosed traits are meaningful.

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

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

The description is very short and information-dense, with no filler or redundant phrases. It front-loads the most critical behavioral constraints. However, the brevity contributes to the lack of definitional clarity.

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 three required parameters, no annotations, and no output schema, this description is far too incomplete. It does not explain what the tool returns, how it makes decisions, what action values are valid, or how the hard cap/allowlist is applied. An agent cannot reliably construct a correct invocation from this description alone.

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 0%, and the description does not mention url, amount_usd, or action at all. It provides no clarification on value formats, allowed actions, or how parameters relate to the hard cap and allowlist. An agent cannot infer parameter semantics from this description.

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 lists constraints (hard cap, allowlist, cannot override, fail closed, write key) but never states an explicit verb and resource, such as 'Checks whether a spend is allowed.' The tool name implies spend checking, but the purpose remains inferred rather than stated. It hints at distinctiveness from siblings through hard cap/allowlist but does not clearly differentiate itself.

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

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

No guidance is given on when to use spend_check versus alternatives like request_approve or decide_approve. The constraints imply some spend-enforcement context, but there is no explicit context, prerequisite scenario, or exclusion. An agent must guess selection criteria.

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 no annotations provided, the description carries the behavioral burden. It discloses a key trait: fail closed, meaning uncertain or failed checks should be treated as failures. It also notes the check is against the live policy, adding useful behavioral context beyond the 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?

The description is only two short sentences, front-loaded with the core action and followed by a critical behavioral note. Every word earns its place, with no fluff or repetition.

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

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

This is a simple one-parameter tool with no output schema, and the description sufficiently explains the outcome ('pass/fail'), the timing ('before recommending'), and the failure behavior ('fail closed'). It does not detail return format or edge cases, but for this tool's complexity, the description is reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only restates 'URL' without adding format constraints, scheme requirements, or other semantics. The property name is self-explanatory, and the description confirms the URL is the object of the check, which is minimally adequate for a single parameter.

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

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

The description clearly states a specific action: pass/fail a URL against the live policy. It is not a tautology and identifies the resource (URL) and the evaluation context (live policy), though it does not explicitly differentiate itself from sibling 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?

The phrase 'before recommending it to a human' gives clear usage context. It does not name alternatives or exclusion conditions, but an agent can infer when this tool should be invoked in a recommendation workflow.

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 no annotations, the description carries the full behavioral burden and does well: it discloses that only attested results are returned, that uniqueness within the pond is prioritized, that nothing will be invented, and that the result is empty when no match exists. It omits side effects and permissions, but these are less critical for a lookup-style tool.

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 extremely compact and front-loaded with the most important instruction. Every phrase earns its place, and it packs meaningful behavioral rules into a very small space 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 3-parameter tool with no annotations and no output schema, the description provides key context: when to call, the attestation constraint, the uniqueness ordering, and empty-result behavior. However, it does not describe the return payload shape or fully explain parameter semantics, so the agent still has to infer what a 'good' result looks like.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only obliquely clarifies 'pond' via 'unique-in-pond first'; query and limit are left entirely to their names and types. No value formats, defaults, or boundary behavior are described.

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

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

The description conveys that the tool should be called before recommending and hints at its purpose through the name, but it never explicitly states a verb and resource or what the tool returns. It does imply a distinction from commit_recommend by positioning itself as a pre-recommendation call, but the core purpose remains vague.

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 invocation trigger: 'Call before recommending.' It also warns against inventing data, which tells the agent this tool should be used instead of guessing. It does not mention alternatives or when not to call, but the timing instruction is clear enough for basic routing.

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