hunchful

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

No annotations provided, so description carries full burden. Discloses ownership trust requirement (OAuth or editToken), that the hunch is visible/revisable/removable, and emphasizes recording only what was said, not invented.

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 front-load purpose, then trust requirement, then behavioral rule and alternative. No fluff; each sentence is essential.

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 main points: purpose, trust, naming, limitations. Output schema exists, so return values need not be described. Complete for agent to select and invoke correctly.

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

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

Schema coverage is 88%, so baseline is 3. Description adds the naming rule 'When <situation>' for situational axes, which extends the example already in schema. Provides context for confidence default, but that is already in 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 records a 'NEW hunch' from conversation, specifying it is a custom axis added to the person's model. It distinguishes from sibling 'suggest_question' by mentioning when to use that instead.

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 just confirmed in conversation') and when not to ('if they haven't answered yet, use suggest_question'). Provides 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?

With no annotations, the description carries full burden. It discloses that the tool appends evidence pointers and nudges confidence, clearly indicating a mutation. It also mentions authorization requirements. Slightly limited in explaining idempotency or side effects, but sufficient.

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 achieve purpose, usage guidance, and authorization – no wasted words. Front-loaded with the core action.

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?

Despite lacking parameter semantics in the description, the schema provides detailed field descriptions for most properties. With an output schema present, the description covers purpose, usage, and transparency well. Missing some context about the array structure, but overall 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?

Schema description coverage is low (33%) and the description adds no parameter details beyond what the schema already provides. It does not explain the structure of the 'items' array or the role of 'modelId', missing an opportunity to compensate for the coverage 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 uses a specific verb ('apply') and resource refinement with clear scope ('refinement directly as one logged revision'). It distinguishes from the sibling 'propose_refinement' by stating a preference for that alternative unless direct writes are requested.

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 advises to 'Prefer propose_refinement unless the owner asked for direct writes', providing clear when-to-use and when-not-to-use guidance. Also specifies authorization via 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?

No annotations provided, so description must carry full burden. It states 'Open read' indicating a read-only operation and mentions output as links. However, it does not disclose authentication requirements or rate limits, and the OAuth dependency is only in parameter description.

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?

Description is short and front-loaded with key concept. It includes explanation of complements and usage, earning its sentences. Minor improvement: could be tighter without losing 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 simple tool with one optional param and output schema, the description covers the concept and output format. However, it lacks explicit mention of the input (the person's model) and how it relates to the task, leaving some contextual gap.

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 parameter description. The description adds OAuth context ('Omit when connected via OAuth') but does not explicitly link the parameter to the person being analyzed. Overall, meaning is adequate but not enhanced beyond 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 finds complementary thinkers (opposites, not similarity), using the verb 'COMPLETE' and specifying 'Open read'. It differentiates from sibling tools like find_matches by emphasizing opposition over 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 gives usage context ('great for curiosity and for explaining what a complementary collaborator looks like') and implies when not to use (not similarity). However, it lacks explicit guidance on alternatives or when to prefer this over 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?

With no annotations, the description carries the full burden. It discloses that the tool creates pending proposals, never reveals identities, and requires specific authentication and a user prerequisite. This adds significant behavioral context beyond a basic function call.

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 conveys key points but is somewhat run-on and could be more structured. It front-loads the primary purpose but then packs multiple pieces of information into long parenthetical clauses.

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 that an output schema exists (though not shown), the description adequately covers the tool's purpose, prerequisites, and behavioral notes. It does not need to explain return values, and the provided context is sufficient for a 3-parameter 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?

Schema coverage is 67% (modelId lacks description). The description adds context for the editToken parameter by mentioning authentication requirements, but does not explain modelId or add meaning to direction beyond what is in the schema. The additional value is moderate.

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, describing the verb 'look for' and resource 'PEOPLE'. It distinguishes from the sibling 'find_complementary_thinkers' by focusing on the connected person's proposals, but does not explicitly differentiate the scope.

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 usage context (agents propose, humans accept) and prerequisites (OAuth/editToken, joined introductions). However, it lacks explicit guidance on when to use this tool versus alternatives like 'find_complementary_thinkers' or other 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?

No annotations are provided, so the description carries full burden. It clearly discloses that the refinement is queued (nothing changes until accepted), required auth (OAuth or contributionToken), and the constraint that source must be a provenance pointer (no free text). This is comprehensive for a non-mutating proposal 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?

Two tightly written sentences with no wasted words. The first sentence states the core purpose, and the second adds critical behavioral and auth context. Structure is 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?

Given that an output schema exists, the description is complete: it covers purpose, usage, behavioral details, auth requirements, and key constraints. The maxItems/minItems limits are in the schema and need not be repeated. No gaps are apparent.

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 33%, but the description adds auth context for modelId and contributionToken. It also reiterates that source is 'Provenance pointer only, e.g. agent:chatgpt. No free text, no names.' which adds semantic value beyond the schema's own description. The observedAt default is noted. Overall, the description enhances understanding of parameters.

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 the tool proposes a refinement using provenance pointers only, clearly distinguishing it from siblings like apply_refinement (which applies changes) and add_hunch (which adds hunches). The verb 'Propose' and resource 'refinement' 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 explains that refinements land in the owner's confirm queue and require authorization via OAuth or contributionToken. It implies when to use (for suggesting changes without immediate effect) but does not explicitly contrast with alternatives like apply_refinement. The constraint on source (provenance pointer only) provides clear 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?

No annotations are provided, so the description carries the full burden. It discloses the read-only nature and output contents, but lacks details on potential errors, rate limits, or data freshness.

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, front-loaded with core purpose, no wasted words. Efficiently covers main usage and special case.

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 an output schema exists, the description adequately covers what the tool returns and its primary use. Could be slightly more thorough for edge cases but is sufficient for most use cases.

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

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

Schema coverage is 100%, and the description adds value by explaining the OAuth behavior and when to omit the parameter, which is beyond the schema's own 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?

Description clearly states the tool reads a Hunchful collaboration model and specifies returned data (hunches, axis ids, connections). It distinguishes from siblings by being the recommended starting point ('Start here.') and notes special OAuth behavior.

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?

Provides explicit guidance on when to omit modelId (with OAuth) and implies it as the entry point. However, it does not explicitly exclude other 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?

No annotations exist, so description carries full burden. It discloses that suggestions land in the inbox, trigger default emails, and nothing is added until the person answers. Authorization via OAuth or token is stated, and the frequency warning adds transparency. 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?

Three sentences, each purposeful: purpose, behavior, authorization+feequency. No filler, front-loaded with key action. Highly 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?

With an output schema present, the description covers all needed context: purpose, behavior, authorization, frequency, and parameter guidance. For a complex tool with 8 params and 4 required, it provides sufficient information for 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?

Schema coverage is 88%, so most params are documented. The description adds value by explaining the 'why' param ('what you observed, no quotes, no names'), guiding 'name' for situational axes, and clarifying auth params (contributionToken for non-OAuth). This goes beyond the schema.

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

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

The description clearly states the tool suggests a new question/axis for a person, specifically a dimension not captured by their model. It distinguishes from siblings like add_hunch or propose_refinement by targeting new axes, and provides formatting guidance for situational axes ('When <situation>').

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 frequency advice ('Use sparingly — about once a week at most') and explains authorization methods (OAuth or contributionToken). While it doesn't directly contrast with siblings, the purpose is distinct enough that an agent can infer when to use it.

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