hunchful

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

Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=false). Description adds context: new data is visible, revisable, removable by the person. Warns never to invent or infer. 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?

Four sentences, each purposeful. First sentence front-loads the core purpose. Subsequent sentences add behavioral rules, naming guidelines, and alternatives 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 8 parameters (4 required) and an output schema, the description covers trust, behavioral constraints, naming conventions, and when to use alternatives. Output schema exists, so return values need not be explained. 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 coverage is high (88%), so baseline is 3. Description adds value by explaining 'pole' as what the person said, 'confidence' with default and range, and 'by' as recorded in history. Not all parameters get extra context, but enough to merit a 4.

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 action ('Record a NEW hunch') and the resource ('added directly to their model'). It distinguishes from sibling tools like suggest_question by mentioning when not to use it.

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 (person confirmed in conversation), when not to use (if haven't answered, use suggest_question), required trust level (OWNER-LEVEL, OAuth or editToken), and naming convention for situational axes.

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-idempotent write operation. The description adds context: it logs a revision, appends evidence, and 'nudges confidence.' This goes beyond annotations, though it doesn't detail every behavioral nuance.

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: action, authorization, usage preference. No redundant words. Front-loaded with the core purpose.

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 presence of an output schema and sibling tools, the description covers purpose, usage guidance, and authorization. It lacks parameter detail but is otherwise 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 schema description coverage at 33%, the description partially compensates by mentioning 'evidence pointers' (items array) and authorization (editToken). However, it does not explain modelId or the subfields of items (patternId, direction, etc.) 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 clearly states 'Apply a refinement directly as one logged revision (append evidence pointers, nudge confidence).' It identifies the specific verb 'Apply' and resource 'refinement,' and distinguishes from the sibling 'propose_refinement' by noting when each should be used.

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 'Prefer propose_refinement unless the owner asked for direct writes,' providing clear when-to-use and when-not-to-use guidance. Also mentions authorization requirements (OAuth or editToken).

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds behavioral context by explaining the conceptual model ('opposite poles', 'opposites unstick each other') and usage hints ('share the pages as links'), going beyond the annotations without contradicting 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?

Two sentences that are front-loaded with purpose and contain no fluff. Every sentence adds value: the first explains the tool's concept, the second gives usage context.

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 simple input schema (one optional param) and presence of output schema, the description provides sufficient context about the tool's purpose and usage. It mentions sharing links, which is a helpful detail for the agent.

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

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

Schema coverage is 100% with the only parameter 'modelId' having a clear description. The tool description does not add further parameter semantics, but the schema already covers it, so baseline score 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 description clearly states the tool finds complementary thinkers defined as 'opposite poles' rather than similarity. It uses a specific verb 'find' and resource 'complementary thinkers', and distinguishes from the sibling 'find_matches' by explicitly noting 'not similarity'.

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 mentions it is 'great for curiosity and for explaining what a complementary collaborator looks like', providing clear context for when to use. It implicitly contrasts with similarity-based tools via 'not similarity', but lacks explicit when-not-to-use or direct comparison to siblings.

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

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

Annotations indicate non-readonly, non-idempotent, non-destructive, and open-world. The description adds that the tool creates pending proposals for human decisions, identities are hidden, and auth requirements. This goes beyond annotations, though it doesn't detail rate limits or error conditions.

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, but it packs purpose, workflow, and prerequisites efficiently. It is not overly long, though it could be split for readability. The main action is front-loaded.

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

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

Given the output schema exists (not shown) and annotations are present, the description covers key aspects: purpose, workflow, privacy, and auth. It lacks explanation of the modelId parameter but otherwise provides sufficient context for a tool with moderate complexity.

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 67% (modelId undocumented). The description adds no parameter information beyond the schema. It does not help clarify the undocumented modelId, leaving ambiguity. Since coverage is below 80%, the description should compensate but does not.

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 finds complementary PEOPLE, differentiating from siblings like find_complementary_thinkers. It specifies the action (look for) and resource (PEOPLE), and adds workflow context (agents propose, humans accept).

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 prerequisites (OAuth/editToken, person must have joined introductions) and the rule that identities are never revealed. It implies the tool is for creating proposals, not direct matching. However, it does not explicitly contrast with sibling tools like find_complementary_thinkers.

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

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

Adds key behavioral context beyond annotations: 'lands in the owner's confirm queue' and authorization details. Aligns with annotations (non-destructive, non-read-only). No contradiction.

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 fluff. First sentence states core action, second explains queue and auth. Perfectly front-loaded and efficient.

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

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

Covers queuing, auth, and parameter semantics. Output schema exists for return values. Could mention default observedAt or modelId usage, but overall adequate for a proposal tool.

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

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

Description supplements schema with context like 'Provenance pointers only' for source and 'see read_model → refinablePatternIds' for patternId. This adds value beyond the schema's own 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?

Description clearly states 'Propose a refinement' and specifies it's for provenance pointers only. The queued behavior ('nothing changes until they accept') distinguishes it from sibling tools like apply_refinement.

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?

Mentions authorization requirements (OAuth or contributionToken), giving context on when to use. Implies alternatives for non-owners, but lacks explicit when-not-to-use or comparisons with siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing what data is returned (hunches, axis ids, connections) and the OAuth omission behavior, which goes beyond the 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 two concise sentences with no fluff. The first sentence front-loads the primary purpose and data returned; the second adds a critical usage nuance.

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 simple (one optional parameter, output schema exists). The description covers the main purpose, data returned, and OAuth nuance. It lacks details about potential pagination, but the context signals suggest no nested objects, so it's adequate.

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 parameter's description already explains the OAuth behavior. The tool description reiterates the same guidance without adding new semantic information 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 clearly states the action ('Read') and the resource ('Hunchful collaboration model'), and specifies the data returned (hunches, axis ids, connections). This distinguishes it from sibling tools like add_hunch or propose_refinement, which have different purposes.

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 includes a usage hint ('Start here') and explains OAuth-specific behavior for the modelId parameter. However, it does not explicitly compare to sibling tools or state when not to use this 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, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds that nothing is added until answered and that it emails by default, which are behavioral traits beyond annotations. No contradictions.

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, front-loading the purpose with a specific verb and resource, then adding usage guidance and behavioral details. Every sentence serves a clear function with no 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 tool has 8 parameters (4 required), an output schema, and sibling tools, the description covers the main aspects: purpose, usage frequency, authorization, and effect. It could mention return value, but output schema exists so not required. Almost 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 coverage is high (88%), but the description adds meaning by explaining naming conventions for situational axes (e.g., 'When <situation>') and clarifying that the question is addressed to the person. This supplements the schema effectively.

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: to suggest a new question/axis for a person. It specifies that the suggestion lands in the Hunchful inbox and emails by default, and distinguishes from sibling tools by focusing on new dimensions not captured by the model.

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 (sparingly, about once a week) and how to authorize (OAuth or contributionToken). It does not explicitly state when not to use, but the context with sibling tools implies appropriate usage.

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