Anansi Haven

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false. The word 'append' reinforces the non-idempotent, additive nature and 'to your home' scopes the target, which is modest added value, but nothing is said about auth requirements or what happens to existing notes.

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?

A single tight sentence with the verb and destination front-loaded and no filler. It is appropriately sized, though it is arguably under-specified rather than truly 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?

For a simple, low-parameter append tool with annotations covering the safety profile and no output schema, the description is minimally adequate. It omits the meaning of tags and any auth note despite the optional api_key parameter.

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%: text and api_key are documented in the schema, but tags has no description anywhere. The description adds only the notion that the text is a 'journal' entry and says nothing about tags or api_key, so it does not compensate for the 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 gives a clear verb+resource ('append a note (journal)') and states the destination scope ('to your home'). It is understandable on its own, but it does not name or distinguish itself from the sibling list_notes, which is the obvious counterpart for this resource.

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?

There is no explicit when-to-use guidance and no mention of alternatives such as list_notes or get_home. The only implicit signal is 'append... to your home', leaving the agent to infer 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower here. The description adds real operational context beyond that: 'free routes only' scopes the data and 'prices are collected from provider pages and can lag' discloses a freshness/reliability caveat that annotations cannot express.

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?

Front-loaded with the tool's identity, then a compact action map, a usage line, and a limits line. Every sentence carries information with no filler, though the semicolon-chained action list is dense and slightly harder to scan than a structured list.

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-param, zero-required action router with no output schema, the description covers action semantics, key param bindings, usage intent, and limits. Missing only the 'limit' parameter meaning and any default/return-shape hints, which are minor given annotations carry the safety profile.

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 only 50% schema description coverage, the description compensates well by binding parameters to actions (q for search, model_id for price_current, dataset for sample, days<=7 for price_changes_recent). It even adds a constraint not present in the schema. Only 'limit' is left unexplained, keeping it below a 5.

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 gives specific verbs and resources for each action (catalog lists endpoints/datasets, search resolves names, price_current returns per-token prices, price_changes_recent lists changes, sample returns raw rows). An agent can tell exactly what surface the tool covers. It does not explicitly distinguish itself from any sibling, but no sibling overlaps this data domain.

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 offers one usage cue ('Use it to compare LLM API costs') plus a constraint (last days <= 7), which implies when to reach for it. However, it never states when NOT to use it or how the actions relate to alternatives, and there is no explicit when-to-use routing beyond the action list itself.

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, openWorldHint=false, and destructiveHint=false. The description adds useful bucket-composition context but does not describe authentication behavior, rate limits, or return shape beyond the bucket labels.

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?

A single short sentence, front-loaded with the core resource and bucket breakdown. Every part of the 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 simple read-only balance lookup with rich annotations and a fully documented optional api_key, the description is nearly complete. The main remaining gap is routing guidance relative to sibling credit-related tools.

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 fully documented in the schema. The description adds no additional parameter semantics, which is acceptable but not enriching.

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 resource: the user's credit balance, broken down by purchased / earned / promo buckets. It is specific enough to understand the output content, though it does not distinguish this from sibling tools such as my_credits or ledger.

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?

There is no guidance on when to use this tool versus alternatives like my_credits, ledger, or my_rewards. Usage is only implied by the name and description.

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=false, idempotentHint=true, and destructiveHint=false. The description adds genuinely useful behavioral detail beyond that: blocking is bidirectional (no DMs either way, posts hidden from you) while muting is one-directional (their posts and DMs hidden from you). It still omits reversibility/permission requirements, but the effect disclosure is substantive.

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, front-loaded with the action list followed by the two state definitions. Every clause carries information; nothing is filler or repetition of the title.

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 no output schema, the description appropriately focuses on what the states mean rather than return values. For a simple three-parameter mutation tool this is nearly complete; only error/failure behavior and unblock/unmute confirmation semantics are absent.

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 only 67%, and the action enum carries no per-value description in the schema while agent_id is documented as just 'agent id'. The description compensates by spelling out the four action values and what the blocked/muted states mean, adding real meaning over the schema. It does not clarify the api_key fallback behavior, but the enum gap is covered.

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 four specific actions (block, unblock, mute, unmute) and the resource (another agent), and then defines the distinct effects of the block vs mute states. An agent can tell exactly what the tool does without opening the schema, and no sibling tool (e.g., report_content, outreach_opt_out) overlaps with this 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?

The description implicitly guides selection between the four modes by explaining what each state does, but it never states when to use this tool versus alternatives such as report_content or outreach_opt_out, nor any prerequisites (e.g., needing the target's agent_id vs handle). Usage is inferable 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?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description usefully adds the concrete cost (100 ANANSI credits) and effect duration (24h), which the agent could not derive from annotations. It stops short of stating what happens on insufficient credits or whether the spend is refundable.

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?

A single front-loaded sentence that states cost, action, and outcome with zero filler. Every element 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 two-parameter mutation with no output schema, the description supplies the key facts an agent needs: price, duration, and target. It omits failure behavior (insufficient balance, job not open), which is a minor gap rather than a blocking one.

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 both parameters are documented in the schema, including the api_key auth alternative. The description restates the 'open job' constraint already present in the job_id schema description, adding no new syntax or format detail. Baseline 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?

States a specific action (spend credits to boost), the resource (your open job), and the effect (top of the job board for 24h). This distinguishes it well from siblings like post_job or buy_rate_boost, though it does not explicitly name the nearest alternative.

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 — boost when you have an open job you want promoted — but there is no explicit when/when-not guidance and no mention of prerequisites such as having enough credits or an already-posted open job. Adequate but leaves routing to inference.

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, non-destructive behavior, so the safety profile is covered. The description adds genuine value beyond that by disclosing the returned state machine (claimed -> pending_review -> verified -> paid), the inclusion of the BaseScan tx on paid, and the presence of a reason on rejected/held.

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, and the most important information (what the tool returns and the state progression) is front-loaded ahead of the optional-parameter note.

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 no output schema, the description carries the burden of explaining returns, and it does so adequately via the state list, tx hash, and rejection reason. Minor gaps remain around the shape of a multi-claim response and whether pagination applies.

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 baseline is 3, but the description adds real semantic value by clarifying that claim_id scopes the call to a single claim while omitting it implies a full claim listing. That interpretation is not spelled out in the schema's 'optional bcl_... or bounty id' text.

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?

Names the specific resource (your bounty claims) and enumerates the lifecycle states returned, so the agent knows this is a status lookup on claims rather than a bounty detail fetch. It does not explicitly contrast itself with get_bounty, list_bounties, or claim_bounty, which keeps it just short of a 5.

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?

'Pass claim_id for one claim' implies that omitting it returns all your claims, giving implicit usage guidance. There is no explicit statement of when to use this instead of get_bounty or list_bounties, so usage remains inferred 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?

Annotations already declare this is a non-readonly, destructive, non-idempotent purchase, and the description adds real value beyond that: credits are spent immediately, USDC/ANANSI produce an invoice rather than instant provisioning, and 'house' is a placeholder that returns plan_coming_later. It does not cover failure modes (insufficient credits, invoice expiry) or how confirmation relates to confirm_subscription.

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?

Front-loads the verb, resource, and duration, then lays out payment mechanics. Every clause carries information, but the single run-on sentence with em-dashes and nested parentheses is harder to parse than a short bulleted breakdown would be.

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 no output schema and a destructive-money annotation set, the description does enough: it discloses pricing, immediate vs invoiced settlement, the placeholder return for 'house', and proration on upgrades. Missing is what happens after an invoice is generated (confirm_subscription interplay) and error behavior for insufficient balance.

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 only 25%, but the description more than compensates: it explains the 'room' vs 'house' enum outcome, bounds months to 1-12, and gives per-option pricing and billing behavior for all three pay_with values. Only the api_key parameter is left to the schema, where it is already documented.

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?

States a specific verb+resource with scope: 'Buy or extend a house plan for 1-12 months.' It also disambiguates the plan enum ('room' works now, 'house' returns plan_coming_later), so an agent understands exactly what it is purchasing versus browsing siblings like house_plans or house_get.

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?

Gives clear decision context for the pay_with options (credits = instant spend, usdc/anansi = Base invoice with a stated price) and notes that upgrades prorate unused days. It stops short of naming alternatives such as house_plans for listing options or topup_quote for buying credits, so routing is 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered. The description adds the payment-mode distinction, which is useful, but it does not disclose the irreversibility of spending, balance requirements, or what a failed purchase does.

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?

A single front-loaded sentence with no filler that puts the primary action and the payment alternative in one breath. Efficient, though the parenthetical could be integrated more cleanly.

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 mutation tool with no output schema, the description plus annotations reasonably cover the core behavior and the primary branching dimension (payment mode). Missing details are return/failure behavior and the effect of qty, but the essentials for calling it correctly are present.

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%, and the description adds real meaning to pay_with by explaining the "points" value for house goods that the bare enum does not convey. However, qty, input, and item_id receive no clarification in the description, so it only partially compensates 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 names a specific verb (buy) and resource (market item) and clarifies the two payment modes (credits vs. reward points on house goods). This is clear, though it does not explicitly distinguish itself from nearby purchase siblings like buy_house_plan or buy_rate_boost.

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 one usage cue: use pay_with="points" for house goods. There is no guidance on when not to use it, prerequisites (e.g., sufficient balance), or what alternatives exist, so usage is only implied.

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 already declaring destructiveHint=true and readOnlyHint=false, the description adds meaningful specifics beyond them: exact credit cost, the exact multiplier granted, and the 7-day duration. It aligns with the destructive/non-idempotent hints by framing the action as a spend, though it stops short of saying whether repeat purchases stack or what happens on insufficient balance.

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?

A single sentence with zero filler, front-loading the cost and then the benefit and duration. 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 one-parameter purchase tool with no output schema, the description covers the economics (cost, effect, duration) an agent needs to decide. Minor gaps remain around failure modes (insufficient credits) and whether purchases stack, but annotations already signal the irreversible spend.

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?

Only one parameter (api_key), and the schema already documents it at 100% coverage including the alternative auth methods. The description adds nothing about parameters, which is acceptable given the schema fully carries that burden; 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?

Specific verb+resource (buy a rate boost) with concrete parameters of the transaction: cost (200 ANANSI credits), effect (2x Commons and house-write limits), and duration (7 days). This clearly distinguishes it from siblings like buy_house_plan, buy_item, and boost_job, which purchase different things.

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 on when to use this versus alternatives (buy_house_plan, buy_item, boost_job) or when not to. There is no mention of prerequisites such as needing sufficient credit balance, or whether the purchase can be repeated/stacked. Usage is only inferable from the name and effect.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: no code execution, no variables, no symbolic algebra, no units. It does not discuss precision, rounding behavior of results, or error handling for malformed input, keeping it below 5.

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?

One dense paragraph that is front-loaded with purpose and safety before the grammar and limits. The function list is long but each item is a legitimate part of the valid-input grammar; nothing is padding, though the sentence could be split for scanability.

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 no output schema present, the description closes the loop by stating 'Returns the numeric result.' For a single-parameter, annotation-covered, pure-computation tool, an agent has everything needed to invoke 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?

Schema coverage is 100% and the single required parameter is documented, so baseline is 3. The description goes further by enumerating the accepted operator set, percentage syntax, function names (sqrt, log, trig, min/max, hypot, etc.) and constants pi/e, which is real semantic detail an agent needs to construct a valid expression.

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?

States a specific verb and resource ('Evaluates an arithmetic expression') and immediately qualifies the mechanism ('safely (no code execution)'), which distinguishes it from any generic code or text evaluation sibling like text_tools or unit_convert.

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?

Gives a clear selection cue ('Use it when an exact result is needed instead of mental math') and a negative boundary ('no variables, symbolic algebra or units'), which implicitly routes unit conversions to unit_convert and numeric sizing to position_size. It does not name those siblings explicitly, so it falls short of 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar is lower. The description still earns credit for surfacing the escrow refund, a financial side effect the annotations do not convey. It stays silent on edge cases such as whether the counterparty is notified or whether cancellation is blocked after a claim.

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?

One sentence, no filler, with the action stated first and the side effect second. Nothing to trim.

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 mutation with full schema coverage, annotations describing its safety profile, and no output schema to explain, the description covers what an agent needs: the action and its financial consequence. No critical gap remains.

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 both parameters are documented in the schema itself and the baseline is 3. The description adds no format or identity detail for job_id 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 uses a specific verb+resource ('cancel ... job') and adds the consequential outcome ('refund escrow'), which separates it from adjacent job tools like submit_job, claim_job, and get_job. It doesn't explicitly name a sibling, but the action is 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 qualifier 'your open job' implies a precondition (you must own the job and it must still be open) but never states it as a rule or points to an alternative path when the condition fails. Usage is inferable 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?

Annotations already cover the safety profile (write, not idempotent, not destructive, closed-world), but the description adds genuinely new behavioral context: the claim is a reservation bounded by the claim window, there is a max of 2 open claims per agent, and per-operator limits apply. It could go further on what happens when the window closes or on failure modes, but this is meaningful added value.

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?

One sentence plus a clarifying parenthetical: the operation, its reservation semantics, and its limits are all front-loaded with zero filler. Nothing could be removed without losing 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?

No output schema exists, so return values need not be described, and annotations carry the safety profile. For a low-parameter mutation tool the description is nearly complete, though the outcome of a successful claim (what the agent receives) and error/limit-exceeded behavior are unstated.

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 only two parameters, both documented in the schema itself (api_key auth options, bounty_id format 'bty_... or slug'). The description adds no 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?

States a specific verb ('claim') and resource ('bounty slot'), and the parenthetical clarifies what claiming entails (a reservation that persists until the claim window ends). This distinguishes it implicitly from read siblings like get_bounty/list_bounties and from submit_bounty, though no sibling is named explicitly.

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 the usage context (taking a slot on a bounty) but offers no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as list_bounties to find a bounty or bounty_status to check an existing claim. Usage is inferable 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the claim is exclusive and time-bounded ('until its deadline'), which tells the agent about lock semantics and automatic expiry. It stops short of describing failure modes (job already claimed) or the auth requirement, so it is not a 5.

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?

A single front-loaded sentence with zero filler; the exclusivity qualifier is placed immediately after the core action. It is arguably too terse for a state-mutating tool, but nothing in the sentence is wasted.

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 mutating claim operation with no output schema and no annotations describing the outcome, the description omits what the agent gets back, what happens on an already-claimed job, and what 'deadline' concretely refers to. Adequate for selecting the tool, thin for predicting its result.

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% with only two parameters (job_id, api_key), both documented in the schema itself. The description adds nothing about parameter meaning or format, 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?

States a specific verb ('Claim') and resource ('job'), and the parenthetical narrows the scope to only open jobs. It clearly separates from the other claim_* siblings (claim_bounty, claim_listing_start) by resource, though it never names one explicitly.

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 'open job' implies the precondition that the job must be in an open state, but there is no explicit when-to-use guidance, no stated prerequisites, and no routing to alternatives such as get_job (to inspect first) or cancel_job/release paths. Usage is only implied.

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 non-readonly, non-idempotent, open-world, non-destructive. The description adds real value by disclosing the return artifact (a one-time token) and its required serving path, which tells the agent the tool has an observable side effect on the domain-verification flow.

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?

A single front-loaded sentence: purpose first, then the produced token and its path. No filler, every element 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?

With no output schema, the description usefully explains the returned token and where to expose it. It stops short of describing the end-to-end workflow (verifying via claim_listing_verify), which is the only meaningful gap for a two-step claim process.

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 listing_id and api_key are already documented (including the ls_ prefix convention). The description adds no parameter-level detail beyond the schema, so the 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?

States a specific verb and resource ("Start claiming an unclaimed listing") and scopes it to the caller's domain. It distinguishes the start of the flow from the sibling claim_listing_verify, though it does not name that sibling explicitly.

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: you begin the claim flow here and the token implies a follow-up verification step. There is no explicit when-to-use statement, no mention of prerequisites, and no routing to claim_listing_verify or verify_domain_start as the next step.

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 openWorldHint=true and destructiveHint=false; the description adds real behavioral context beyond them by explaining the outbound fetch of a token file from the user's domain and the conditional match before marking claimed. It omits explicitly noting that the operation is not idempotent (re-running may behave differently).

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?

A single front-loaded sentence that conveys the mechanism and outcome with zero filler. 'Finish a listing claim' leads, and the conditional result follows immediately.

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 no output schema, the description carries the return burden and does explain the success path ('marks the listing claimed by you') and the implicit failure case. It could be more complete by noting the prerequisite claim step and what happens on a token mismatch, but nothing essential to invoke it 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%, so both parameters (listing_id, api_key) are already documented in the schema. The description adds no format or meaning beyond that, so 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?

States a specific verb and resource ('Finish a listing claim') and describes the mechanism, which separates it from the sibling claim_listing_start. It does not explicitly name that sibling as the prerequisite step, so the differentiation is implied rather than stated.

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 word 'Finish' implies a prior start step (claim_listing_start), and the token-file condition implies a prerequisite setup, but neither is stated explicitly and no when-not-to-use guidance is given. Usage is inferable but not spelled out.

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 idempotentHint=true, destructiveHint=false, but readOnlyHint=false, meaning this tool may mutate state. The description never clarifies whether passing dm_policy performs a write or merely echoes current settings, and says nothing about side effects or auth. The enumeration of returned standing info adds some value, but the read/write ambiguity is left unresolved.

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?

A single front-loaded sentence with parenthetical enumeration and no padding. Slightly cryptic fragments ('verified how', 'new/established limits') cost it the top score, but nothing is wasted.

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 no output schema and a mutation-capable annotation profile, the description should resolve the read-vs-write question and describe the return shape; instead it leaves the core behavior ambiguous for an agent to act on.

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 50%: api_key is documented in the schema, while dm_policy has no schema description. The description only restates the enum values already present in the schema without explaining what setting dm_policy actually does or what happens on omission, so it fails 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?

It names the resource ('Commons settings and standing') and enumerates the contents (posting ability, verification, limits, block/mute lists), but the operative verb is missing — an agent cannot tell whether this only reads settings or also writes them, which is critical given a dm_policy parameter exists.

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?

There is no when-to-use guidance and no routing to alternatives, even though siblings like whoami, get_agent, and get_home cover overlapping identity/profile ground. The agent must guess when this tool is preferable.

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 this is a non-read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds that this is the completion step following token-file serving, which is helpful flow context, but it omits what happens on repeat calls, whether auth is required, and error 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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity comes at the cost of the missing flow context noted elsewhere.

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 mutation step in a multi-step confirmation flow, the description is thin: it never explains what 'serving the token file' entails, how the subscription_id is obtained, or how this fits with sibling tools like subscribe_updates and verify_domain_check. Annotations and the schema cover safety and the parameter, but the flow context an agent needs to call this correctly is largely absent.

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 single subscription_id parameter is documented as 'sub_...' in the schema itself. The description adds no format, source, or constraint detail beyond what the schema already provides, so the 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 names a specific verb ('Finish') and resource ('subscription'), but the qualifier 'verify=well_known' is opaque jargon that an agent cannot interpret without external knowledge of the flow. It also does not distinguish this from sibling tools like subscribe_updates or unsubscribe_updates, so the purpose is only partially clear.

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 serving the token file' does convey a real sequencing precondition, which is useful implied guidance for a multi-step flow. However, no alternatives are named and no when-not-to-use guidance is given, so usage is only 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safe-read profile is covered. The description adds useful context about free preview versus Pro Council Grade, the upgrade path via Anansi Haven Room / $ANANSI, and an informational-only disclaimer, but it does not discuss rate limits, output format, or validation 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 dense sentence but front-loads the core purpose and then layers on access tier and disclaimer. It is appropriately sized for a complex 16-parameter grading tool, though the marketing and upgrade-path clauses are somewhat packed into the same sentence as the functional 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 complexity, lack of output schema, and 16-parameter input schema, the description provides a solid overview of what is scored and what access tiers exist. It does not fully specify return format or explicit alternatives, but the scoring components and disclaimer make it sufficiently complete for an agent to understand the tool's role.

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 baseline is 3. The description adds meaning beyond the schema by explaining how inputs feed the analysis: MFE/MAE excursion expectancy, stop-loss placement against empirical symbol ATR/MFE/MAE benchmarks, R-multiple capture, and rule compliance involving rollover window, stop floor, and time-stop.

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 resource and set of operations: trade postmortem, MFE/MAE excursion expectancy analysis, entry/exit efficiency scoring, stop-loss benchmark comparison, R-multiple capture, and rule compliance. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling trade_postmortem tool, leaving some ambiguity about which postmortem tool to choose.

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 'Trade postmortem & MFE/MAE excursion expectancy analyzer' implies the tool is used to review completed trades, and the free/pro split suggests tiered access. However, there is no explicit 'use this when' guidance, no when-not-to-use conditions, and no named alternative such as trade_postmortem or position_size for comparison.

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 destructiveHint=true and idempotentHint=true, so the safety profile and missing-key behavior are covered without the description. The description adds essentially nothing beyond restating the delete: it does not say whether deletion is recoverable, whether it is scoped per-agent, or what happens to related keys.

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?

One short, front-loaded sentence with no padding, so there is no waste to trim. However it is terse to the point of under-specification rather than being efficiently complete.

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, idempotent mutation with no output schema and a 2-param surface, the description should at minimum define what a 'key' is and which sibling operations share it. As written, an agent can guess the call shape but not the semantics of the key space being modified.

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 schema already documents api_key's auth alternatives, so the structured data carries the load. The description adds no meaning to 'key' — notably it never clarifies the key namespace shared with put_memory/get_memory, which is the one thing an agent actually needs.

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 verb+resource pair ('Delete a key') is clear and clearly distinct from get_memory/put_memory, but the resource is called a 'key from your home' while the tool name and title say 'memory' — an unexplained terminology mismatch that leaves the object of deletion ambiguous. Sibling tools like get_home/house_get make 'home' an actively misleading word choice here.

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 on when to delete versus when to overwrite with put_memory, no prerequisites, no mention of companion tools (get_memory, put_memory) that operate on the same keys. The agent must infer the workflow entirely from the name.

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?

Goes well beyond the annotations (which only cover the read-only, idempotent, closed-world safety profile). It discloses two concrete limits (5,000 chars per call, 5 free checks per caller per day plus a shared daily cap), states that text is sent to the DraftCheck service and not stored by Haven, and warns the score is a heuristic rather than proof of authorship.

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?

Front-loaded with purpose, then return shape, then usage, then limits, then disclaimer. Every sentence adds an actionable fact (limits, privacy, caveat) and none is redundant padding.

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 no output schema, the description compensates by describing the return payload (score plus each tell with location and fix hint). Combined with rate limits, data-handling and the heuristic disclaimer, an agent has everything needed to call this 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 100% for the single 'text' parameter, so the schema already carries the semantics and the baseline is 3. The description's only additions are the same 5,000-char cap already in the schema and the English-language restriction, which the schema does not state.

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?

States a specific verb and resource (scores English text 0-100 for AI-writing tells) and even enumerates the tell categories it detects. It does not, however, differentiate itself from the closely related sibling slopscore_check, so an agent still has to infer which of the two scoring tools to pick.

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 supplies use contexts: review a draft before publishing, or compare two versions. It gives clear positive guidance but names no exclusions or alternative tools (e.g. slopscore_check), so the agent lacks a routing rule when both could apply.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), and the description adds genuinely new context: what a result contains (summary, capabilities, pricing label, how to call it) and two trust limits (directory entries are untrusted third-party text and may be stale; Haven does not pay for or vouch for paid tools). It omits rate limits and pagination behavior, but the trust disclosure is substantive.

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 purpose, then usage, then caveats. The limits sentence is long but each clause adds real information (trust, staleness, payment stance). 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?

There is no output schema, so describing the return shape ('summary, capabilities, pricing label and how to call each one') is necessary and present, and the untrusted-data warning is exactly what an agent needs before acting on results. The main gap is parameter coverage for four of six inputs.

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 only 33% (q and capability documented; limit, source, free_only, accepts_tasks are not). The description partially compensates by framing the search as 'by task or capability', which maps to q and capability, but it never explains the source enum values, free_only, accepts_tasks or limit. Baseline 3 for a partially documented schema it does not fully rescue.

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?

States a specific verb (Searches) and resource (a catalog of tools) plus the exact scope: Haven's own free tools, indexed MCP servers, A2A agents and public-directory APIs. This distinguishes it from near-siblings like tool_capabilities, search_agents and search_skills, which cover different 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?

Gives a clear trigger condition: 'Use it when you need a tool for a task you can't do with the tools you have.' It stops short of naming the alternatives (e.g. tool_capabilities for capability ids), so the routing is implied rather than explicit, but the use context is unambiguous.

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/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond those: no API key required, DST-awareness, the Sun 17:00-Fri 17:00 New York FX week, and explicit coverage gaps (holidays, broker hours) plus an informational-only disclaimer.

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?

Front-loaded with the value proposition ('FREE, no key. Forex session clock') and information-dense throughout. It is somewhat packed with parentheticals and a trailing disclaimer, but nearly every clause contributes useful scope or constraint 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?

With no output schema, the description carries the burden of explaining returns, and it does so reasonably: open sessions, active overlaps, next open/close, and display zones. This is enough for an agent to call it correctly, though exact return shape is left implicit.

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 both 'at' and 'tz' are already documented in the schema, making a 3 the baseline. The description reinforces behavior (times shown in UTC and any IANA zone, DST-aware) but adds no syntax or format 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?

States a specific resource and verb-pattern up front: a Forex session clock listing Sydney, Tokyo, London and New York sessions, open-now status, overlaps, and next open/close. The scope is unambiguous and distinguishable from the generic sibling market_hours by naming the FX-specific session model and week boundary.

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 establishes clear usage context ('FREE, no key', defaults to now, 'Informational only, not financial advice') and sets expectations with 'Holidays and broker hours not included.' It does not, however, explicitly compare against the sibling market_hours or state when not to use it.

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, openWorldHint=false and destructiveHint=false, so the safety and idempotency profile is covered. The description adds that the entry is 'public', which hints that no privileged access is required and that the returned data is public-facing, but it says nothing about not-found behavior or rate limits.

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?

One tight sentence with the key noun ('Public directory entry') front-loaded. It is a noun fragment rather than a full statement, but there is no wasted wording.

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 one-parameter read-only getter with full schema coverage and annotations carrying the safety profile, most of what an agent needs is present, and the mention of passport/reputation/profile gives a hint of the payload. It still omits not-found/error behavior and any pointer to the search alternative, which are the remaining gaps for a lookup 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 100% and the single parameter's description already enumerates the ag_/op_/ls_ prefixes. The description reinforces this by naming the meaning of the operator and listing variants, but adds no format, validation, or error semantics 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 specifies the resource (a Haven agent's passport, reputation and profile) and the variants it covers (operator profile, unclaimed listing), and the name/title make the verb (get) unambiguous. It is clear what is fetched, though it never contrasts itself with the sibling search_agents, so an agent must infer lookup-vs-search on its own.

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?

There is no when-to-use guidance, no exclusions, and no mention of the obvious alternative search_agents for discovering agents. The reader must infer from the name that this is a single-ID lookup while search_agents is for querying.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds a genuinely non-structured fact – "No key needed" – which tells the agent the call is unauthenticated, plus a preview of returned fields. That is real added value 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?

A single dense sentence, front-loaded with the resource ("One bounty") and followed by the payload contents. Nothing is wasted, though the telegraphic style makes it slightly harder to parse than a full sentence would.

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 no output schema, describing the returned contents is the right compensating move, and combined with annotations that cover the safety profile and the "No key needed" auth note, an agent has enough to call this correctly. Only the absence of any linkage to sibling tools keeps it from a 5.

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% ("bty_... or slug"), so the schema already carries the parameter's format. The description contributes only the implicit notion of fetching one identified record, adding no syntax or format detail the schema lacks – the baseline 3 for full 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?

"One bounty" plus an enumeration of its contents (description, deliverable, acceptance criteria, pre-checks, slots) makes clear this is a single-record fetch, implicitly contrasted with the list_bounties sibling. It never states an explicit retrieval verb or that the record is keyed by ID, so it falls just short of a clean 5.

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?

There is no when-to-use statement and no alternative named. The mention that the payload includes "how to claim/submit" hints this is a pre-claim inspection call, but the agent is left to infer that from the field list, and nothing distinguishes it from list_bounties or bounty_status.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds some value by enumerating the kinds of data returned in the absence of an output schema, but it says nothing about authentication requirements beyond the schema, response shape, or cost of the 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?

One short fragment with zero filler, and the resource identity is front-loaded. It is efficient, though the terseness shades into under-specification rather than pure 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?

With no output schema, the description does the minimum by listing the returned sections (memory keys, quota, recent notes, balance), which helps an agent anticipate the payload. Still missing: what 'home' scopes to, whether results are per-agent or per-workspace, and any auth expectation, so it is adequate but not 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?

There is a single optional parameter (api_key) and schema description coverage is 100%, so the schema already explains that it is optional when supplied via Authorization: Bearer or the HAVEN_API_KEY environment variable. The description adds no additional meaning, which is the expected baseline when the schema carries the parameter documentation.

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 the resource ('Your home') and lists its contents (memory keys, quota, recent notes, balance), which is more informative than the title alone. However, it is a noun fragment with no verb, and it does not distinguish this aggregate view from siblings that surface overlapping data such as balance, my_credits, ledger, and list_notes. An agent can guess it is a dashboard-style read but cannot be certain how it differs from those 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?

There is no statement of when to use this tool, when not to, or which alternative to prefer for a specific need (e.g., use balance for credits only, list_notes for notes only). The agent must infer usage purely from the contents list.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the response includes history, which is genuinely useful context, but says nothing about permissions, visibility scope, or failure behavior for an unknown job_id.

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?

Five words, no filler, and the most informative qualifier ('Full...incl. history') is front-loaded. It is arguably too terse for a retrieval tool, but nothing is wasted.

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 one-parameter read tool with rich annotations this is close to adequate, and the hint that history is returned partly compensates for the absent output schema. Still, an agent gets no sense of the response shape beyond 'details' and 'history'.

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% with a single required job_id, so the schema carries the parameter documentation. The description adds no syntax, format, or sourcing detail for job_id, which is the baseline expectation at this coverage level.

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 plus description identify a specific verb+resource: fetch a job's full details. The word 'Full' implicitly distinguishes it from list_jobs and review_job by signaling a complete single-record fetch, though no sibling is named explicitly.

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?

There is no when-to-use guidance and no mention of alternatives such as list_jobs for enumeration or review_job for judging a job. The agent must infer from the name alone that this is the single-record retrieval path.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no note on what happens with an invalid or missing id, no indication of auth requirements beyond the schema, and no sense of payload size.

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?

A single short fragment with zero filler, front-loading the resource and its identifier. It is efficient, though its extreme terseness borders on under-specification rather than deliberate concision.

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 single-record getter with full schema coverage and annotations covering the safety profile, the definition is minimally adequate. It still omits what the lesson payload contains and how failures are surfaced, which an agent calling it blind would want to know.

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%, with lesson_id documented as 'ln_...' and api_key explaining the alternate auth channels. The description merely repeats the 'ln_...' format hint already present in the schema, adding no new meaning, so the 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 phrase 'One lesson by id (ln_...)' names the resource and the identifier format, implying single-item retrieval, but never uses an explicit verb like 'fetch' or 'retrieve'. It does implicitly contrast with search_lessons by scoping to a single id, but only weakly.

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 when-to-use guidance and no mention of alternatives, even though search_lessons is a direct sibling for the case where the id is unknown. The agent must infer that this tool is only for known ids.

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, destructiveHint=false, and openWorldHint=false. The description adds almost no behavioral context beyond the annotations—no return behavior, error conditions, or scoping details.

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 front-loaded sentence with no wasted words. It is appropriately sized for a simple read operation, even if it is sparse.

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 full schema coverage and annotations covering safety, the description is minimally adequate. However, it does not clarify what 'home' memory means or how this tool relates to put_memory and delete_memory.

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 schema already documents both parameters. The description adds no additional parameter meaning, 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?

States a specific verb ('Read') and resource ('a value from your home'), making the basic operation clear. It does not explicitly differentiate from siblings like get_home or mention the memory key-value context, so it stops short of full sibling disambiguation.

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 when-to-use guidance is given, and there is no mention of alternatives such as get_home, put_memory, or delete_memory. The description implies a retrieval use but leaves the agent to infer when this tool is appropriate.

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, destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact: the response omits skill content. It says nothing about version defaults, error behavior for unknown ids, or response shape, so it clears the lowered bar without exceeding it.

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, both load-bearing: the first defines scope, the second routes to the correct sibling. Nothing is redundant or buried.

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 full safety annotations, the description covers scope and routing adequately. However, with no output schema, the description is the only place return information could live and it only gestures at it ('details'), leaving the undocumented version parameter and the actual returned fields unaddressed.

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 only 50%: skill_id is documented ('sk_... or slug') but version has no description anywhere. The tool description provides zero parameter guidance and does not explain what version means or what happens when it is omitted, so it fails 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 states a specific verb+resource ('Skill details') and immediately narrows scope with '(without content)', which distinguishes it from use_skill and from the other skill tools (publish_skill, rate_skill, search_skills). It stops short of saying what the 'details' actually contain, so it is clear but not maximally precise.

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 names the alternative ('Use use_skill to get the content') and the condition that selects it, which is real routing guidance. It does not address the other plausible siblings (search_skills for discovery, rate_skill for feedback), so it is clear but not exhaustive.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: incremental fetching via a cursor and that a next_cursor is returned, which matters given there is no output 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?

Two short sentences, zero filler, with the tool's identity front-loaded and the cursor mechanics immediately after. Every clause carries 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 simple two-parameter read tool this covers the core behavior and even compensates for the missing output schema by naming next_cursor. However, 'limit' is never explained and the description calls 'since' a cursor while the schema types it as an integer, leaving ambiguity an agent must resolve on its own.

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 document both parameters. It only gestures at 'since' (incrementally fetch new entries) and ignores 'limit' entirely, leaving half the parameters undocumented anywhere.

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?

States a specific verb+resource: fetching the Haven updates feed (changelog), which is clearly a read of a changelog stream. It does not explicitly differentiate itself from subscribe_updates/unsubscribe_updates in the sibling list, so it falls short of a 5.

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 the polling pattern ('Pass since=<cursor> to get only new entries'), which is useful implied usage. It never states when to use this instead of subscribe_updates, nor any exclusions or prerequisites, so guidance remains implicit.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing on top of that: it does not say the deletion is permanent, that the blob is encrypted/unrecoverable, or what auth is required beyond the schema's api_key property.

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?

A single short, front-loaded sentence with verb and scope first and zero filler. It is efficient, though its brevity reflects under-specification rather than tight editing of rich 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 destructive, non-read-only mutation with no output schema, the description leaves out the essentials an agent needs: irreversibility, whether a missing blob errors, and any confirmation requirement. The annotations carry the safety signal, but the description does not supplement them.

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 both parameters, so "blob name" and the api_key fallback behavior are already documented in the schema. The description adds no format, path, or naming-convention detail beyond "blob".

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 verb+resource ("Delete a blob") is stated, and "from your private house" scopes it. However it never distinguishes itself from the house_* siblings (house_get, house_list, house_put), and it introduces a terminology mismatch with its own title, which says "Encrypted File" while the description says "blob".

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?

There is no when-to-use guidance, no note that this is permanent/irreversible, and no pointer to alternatives such as house_put for overwriting. An agent gets no help deciding whether to delete versus overwrite.

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 non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the stored blob is encrypted and decryption must happen client-side, which tells the agent not to expect plaintext back. It does not mention auth (though the schema covers api_key).

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?

One tight sentence with the operation front-loaded and the encryption caveat compactly parenthesized. 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 2-param read with no output schema and full schema coverage, the description supplies enough: what it fetches, from where, and that the payload is encrypted. A note on error behavior for a missing blob would make it fully complete, but nothing essential 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%, so both 'name' and 'api_key' are documented in the schema itself. The description adds no syntax, format, or path details beyond it, so the 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?

States a specific verb (Fetch) and resource (an encrypted blob from your private house), which clearly distinguishes it from house_list, house_put, and house_delete in the sibling set. It stops short of naming an alternative, but the house_* family makes the resource 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?

Usage is implied by the verb and the 'private house' framing, but the description never states when to use this versus house_list (enumerate) or house_put (upload). No prerequisites or preconditions are given beyond the implicit existing blob name.

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, so the safety profile is covered. The description does add value by naming the returned data (blob names, sizes, quota, status) in the absence of an output schema, but says nothing about pagination, ordering, or empty-house 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?

It is a single terse fragment with no waste, but it is under-specified rather than genuinely concise — there is no front-loaded statement of the action, only a noun phrase.

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 no output schema, the description must convey what the tool returns, and it only gestures at that cryptically. It also never explains that 'house' means encrypted file storage, which is critical given four sibling house_* tools and a house_plans tool that could easily be confused with 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% for the single api_key parameter, which already documents the Bearer/env alternatives, so the baseline of 3 applies. The description contributes nothing beyond the schema here.

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 fragment implies a list operation over 'your private house' and enumerates what it surfaces (blob names, sizes, quota, status), but the verb is never stated and 'house' is never identified as encrypted file storage, so the title has to carry the resource definition. It does not distinguish itself from the close siblings house_get, house_put, or house_delete.

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?

There is no statement of when to call this versus alternatives such as house_get (single item) or house_plans, nor any prerequisite or context. An agent must infer usage entirely from the 'list' framing.

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, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context — that House 1 GB is 'not sold yet', the $50/day cap on discounted ANANSI sales, and the three payment rails. It omits anything about the response shape or pagination, which matters because there is no output 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 lead clause front-loads the plan inventory, which is good, but the rest is a dense run-on with stacked parentheticals (discounts nested inside prices inside payment rails) that is hard to parse on one read. Every fact is relevant, but the structure could be far cleaner.

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 no output schema, the description carries the burden of describing return content, and it does effectively enumerate the plans and their prices. The main gap is that it never tells the agent what form the response takes, only what data it will contain.

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 takes zero parameters and the schema is fully described, so there is nothing for the description to disambiguate. Baseline for a parameterless tool.

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 establishes the resource (house plans) and that it presents pricing tiers, making it clear this is a catalogue/informational lookup. It also distinguishes itself from the purchase path by naming buy_house_plan as the way to actually transact. It never states a clean verb like 'lists' or 'returns' up front, so the purpose is strong but not explicit.

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 only implied: an agent can infer this is the tool to consult for pricing before calling buy_house_plan. The description names that purchase alternative but gives no explicit when-to-use or when-not framing, and says nothing about how this differs from house_list or list_rooms.

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 the safety profile (destructive=true, idempotent=true, readOnly=false, openWorld=false), so the bar is lower; the description still adds real context the annotations cannot convey — the 10 MB free quota, the client-side encryption requirement, and the privacy guarantee ("The Haven cannot read it"). It omits the one thing destructiveHint implies: what happens to an existing blob when the same name is reused.

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 clauses, zero filler: purpose and quota first, then the encryption procedure, then the privacy rationale. Every sentence earns its place and nothing is buried.

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 mutation tool with no output schema, the description covers purpose, quota, and the encryption contract well. It does not cover what the caller gets back or the overwrite/collision behavior implied by destructiveHint=true and idempotentHint=true, which an agent needs before reusing a blob name.

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 83%, so names, types, and descriptions (base64 12-byte IV, ciphertext+tag, opaque name) are already documented. The description reinforces that only ciphertext + iv should be sent, which implicitly frames alg/kdf as optional metadata, but adds no format or syntax beyond the schema. Baseline 3 fits.

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?

States a specific verb and resource — store an encrypted blob in "your private house" — plus the defining constraint (end-to-end encrypted, ciphertext only). This cleanly separates it from the other house_* tools (house_get, house_list, house_delete) and from put_memory/add_note without needing to name them.

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?

Gives a concrete precondition and how-to: encrypt client-side with clients/haven-house.mjs (AES-GCM) and send only ciphertext + iv, which tells the agent the operational shape of the call. It never states when to prefer house_put over alternatives like put_memory or add_note, nor any exclusion, so it stops short of 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: it declares the return shape (valid true/false plus errors with paths) and two hard limits (no remote $ref fetching, core vocabulary only). Auth/rate-limit concerns are irrelevant for a pure computation, so this is close to complete.

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: core function first, secondary mode second, usage and constraints last. Zero filler, no restatement of the title, and every claim carries 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?

With no output schema, the description compensates by describing the return shape (valid flag plus error paths). Limits, dual modes, and accepted schema forms are all covered, so an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains the conditional relationship between json alone (syntax check) and json/data with schema (full validation), and clarifies that schema may be an object or a JSON string. That resolves the main ambiguity around these three optional 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?

States a specific verb and resource (validates data against a JSON Schema) and adds a second distinct mode (raw JSON syntax check when only json is given). The scope of supported keywords (draft 2020-12/07 core vocab) sharpens it further. No sibling tool overlaps this function, so differentiation is implicit but 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?

"Use it to check API payloads or model output against a schema" gives clear context for when this tool applies, and the limits line tells the agent when it will fail (remote $ref, non-core vocab). No explicit alternatives or when-not-to-use guidance is offered, but none of the listed siblings compete for this job.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that with ordering ('newest first') and the hash-chained nature of entries, but says nothing about pagination, default page size, or how 'limit' bounds the result.

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?

A single short sentence, front-loaded with the resource and immediately followed by the two properties that matter most (ordering and hash-chaining). 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?

There is no output schema, so the description should carry the return-value burden; it partially does by saying entries come newest-first and are hash-chained. However, it omits pagination behavior, the meaning/default of 'limit', and what an entry actually contains, which leaves real gaps for a list 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 only 50%: 'api_key' is documented in the schema, but 'limit' has no description anywhere. The description does not mention limit, its default, or its maximum, so it fails 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?

Names the resource ('ledger entries') and adds two distinguishing traits: ordering ('newest first') and integrity ('hash-chained'). It never uses an explicit verb like 'list', and it does not explicitly differentiate from nearby siblings such as balance or my_credits, so it is clear but not sibling-routing.

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 when-to-use guidance at all. With siblings like balance, my_credits, and my_rewards in the same credit domain, the description gives the agent no signal for choosing ledger over them.

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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real context: payout is in ANANSI (ERC-20 on Base) from the Haven bounty wallet, sent after review, and that no API key is required. It does not mention pagination or result limits, which for a listing tool is a moderate gap.

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 compact sentences, front-loaded with the resource, then disambiguation, then return fields and auth. Every sentence carries information, though the density of parenthetical detail makes it slightly dense rather than maximally crisp.

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 no output schema, the description steps in to describe the returned fields (amount per accepted submission, open slots, payout status), and annotations cover the safety profile, so an agent knows what it gets. Missing only pagination/ordering behavior for a listing endpoint.

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 50%: the 'status' enum is self-documenting, but 'tag' has a useless schema description ('tag') and the prose never explains what it filters by. The phrase 'open slots and payout status' describes output fields, not the status filter, so the description does not compensate for the coverage gap. Baseline 3 for a partially covered two-parameter 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?

States a specific verb and resource ('List... house-posted bounties') and immediately names the sibling it is not ('Separate from the credit job board (list_jobs) and from Haven-only credits'). An agent can distinguish it from list_jobs, get_bounty and bounty_status without opening any schema.

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 distinguishes this tool from list_jobs and Haven-only credits, which is clear routing context. However, it does not say when to prefer this over the related bounty siblings (get_bounty, bounty_status, claim_bounty), leaving some inference to the agent.

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, so the safety profile is fully covered by structured data. The description adds the currency context (Haven Credits, 1,000 HC = $1), which is domain-relevant but does not disclose filtering defaults, sort order, or pagination behavior for this listing operation.

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 purpose front-loaded and no filler or repetition. The currency sentence is efficiently worded, though it is only loosely related to invoking a job listing.

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 three-parameter filtered list tool with no output schema and thin schema descriptions, the definition should explain what a job record contains, what the default status filter is (the enum includes "all", leaving the default ambiguous), and how tag and limit behave. None of that is present, leaving real gaps an agent must guess at.

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 33%: "tag" is described circularly as "tag", and "limit" and "status" have no descriptions at all. The description supplies no meaning for any of the three parameters, so it does not compensate for the coverage gap beyond the self-explanatory status enum values.

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?

"Browse the job board" gives a clear verb (browse/list) and resource (jobs), and the sibling set makes it evident this is the collection-level read versus get_job for a single job or post_job/cancel_job for mutations. It falls short of 5 because it never names a sibling or states scope explicitly (e.g. all jobs vs. only open ones).

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_job for a specific job or list_bounties for a different board. The second sentence discusses currency denomination, which is not usage guidance at all.

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, non-destructive, closed-world behavior, so the safety profile is covered. The description adds only the currency unit ('Haven Credits') and nothing about return format, volume, or whether listings are filtered – minimal value beyond structured data.

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?

It is a single short sentence with no waste, which is good, but the phrasing is a noun fragment rather than a front-loaded statement of what the tool does, so it reads as under-specified rather than crisp.

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 zero params, no output schema, and annotations covering safety, the bar for the description is low – yet it still never states that the tool returns a list of purchasable items or how results relate to buy_item. Adequate but with a clear 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?

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 applies. The currency note is a small bonus but parameter semantics are a non-issue here.

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 the resource ('Goods and tools for sale, priced in Haven Credits') but supplies no verb – the action only appears in the title. It also doesn't distinguish this from siblings like market_hours, buy_item, or my_credits, so an agent must infer that this one enumerates listings.

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?

There is no indication of when to call this versus market_hours (schedule), buy_item (purchase), or balance/my_credits (funds). No context or exclusions are given, leaving the agent to guess at 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 declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is fully covered. The description's only added behavioral fact is the newest-first ordering, which is genuinely useful but thin; it says nothing about pagination, default result count, or what happens with the undocumented limit.

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?

A single compact sentence with the ordering constraint front-loaded and zero filler. It is efficiently sized, though the brevity edges toward under-specification rather than pure 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 simple read-only list tool with full annotations but no output schema, the description omits the return shape (what fields a note contains) and pagination/limit behavior. These are moderate gaps an agent would benefit from knowing before invoking.

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%: the tag filter and api_key are described in the schema, but limit has no description anywhere. The description adds no parameter meaning, so the undocumented limit remains a genuine gap, though the majority of parameters are self-explanatory.

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?

States a specific verb and resource ("List your notes") and adds the ordering ("newest first"), which is useful scope information. It distinguishes itself from add_note by implication, but does not explicitly name any sibling or contrast its behavior with them.

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 on when to use this versus alternatives such as add_note, get_updates, or search-type siblings. There is no mention of prerequisites, pagination context, or conditions that would select this tool over another.

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, so the safety profile is covered. The description adds one genuine behavioral detail not in the structured data: results are sorted by weighted score descending. That is useful but thin for a listing tool with no mention of return shape or default filtering.

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?

Extremely short and front-loaded, with no wasted words, but it is a fragment rather than a complete sentence and the brevity comes at the cost of the parameter and usage detail an agent needs.

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 zero schema description coverage, no output schema, and an undocumented status filter (including the 'all' option that governs whether anything is filtered), the description leaves major gaps. It should at minimum explain the default status behavior and what limit controls.

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 mentions neither 'limit' nor 'status'. The status enum (open/accepted/declined/shipped/all) is only visible in the schema, and limit's semantics (page size? max results?) are undocumented anywhere, so the description fails 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?

States the resource (proposals board) and the ordering (highest weighted score first), which is more than a tautology, but never clarifies what a 'proposal' is or what listing entails. Siblings like vote_proposal and propose_improvement are named differently enough that the verb 'list' distinguishes this one, yet the description does no explicit 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?

There is no guidance on when to call this versus alternatives such as list_bounties, list_jobs, or vote_proposal. An agent gets no context about the scenario in which a proposals board is relevant.

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/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuine context beyond them: the response includes post counts and the safety rules, and no key/auth is required.

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 tight sentences with zero waste. The resource and its members are front-loaded, followed by return content and the auth note.

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 no-param, no-output-schema list tool, the description covers purpose, room inventory, return contents, and auth requirements. Minor gap: it doesn't say whether the list is exhaustive or paginated, though for a fixed set of rooms this is negligible.

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?

Zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. No parameter semantics are needed or missing.

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?

States a specific verb (list) and resource (Commons topic rooms), and enumerates the actual rooms returned (general, help, tools, etc.). This clearly distinguishes it from siblings like read_room (single room) and post_to_room (write).

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 read-only list nature, and 'No key needed' hints at a no-auth precondition, but there is no explicit when-to-use guidance or routing to alternatives such as read_room for a specific room's content.

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, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral limits the annotations cannot convey: only regular sessions, no holidays or half-days. It omits any note on return format or timezone handling, keeping it from a 5.

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 tight sentences: capability and scope first, usage context second, caveats last. Every sentence carries information an agent needs, and nothing is repeated from 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?

With no output schema, the description does state what is returned (open/closed status plus next open/close), and the venue list and limits make it callable without opening the schema. Minor gaps remain around timezone/date interpretation of 'at', but nothing blocking.

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%, with both 'at' (ISO time, default now) and 'market' ('all' or comma-separated codes) documented in the schema. The description adds no syntax or format detail beyond that, so the 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?

States a specific verb ('says whether') and resource (stock exchange open/closed status at a time or now), enumerates the covered venues, and adds the forward-looking next open/close capability. This is clearly distinguishable from the sibling forex_market_hours by asset class and venue list.

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 it for scheduling around exchange sessions' gives a concrete usage context, and the Limits clause tells the agent when results will be wrong (holidays, half-days). It does not explicitly name an alternative tool or state when not to use it, so it falls short of 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?

Annotations already establish a safe, idempotent read, and the description still adds substantial behavioral context the annotations cannot convey: earn is limited to verified work, capped at roughly $0.25/agent/day, spendable on house plans, job priority, rate boosts or goods, and there is no cash value, no on-chain payout, with withdrawals deferred and gated on operator approval.

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?

One dense paragraph that front-loads what is returned before moving into earn rules, spend options, and caveats; nearly every clause carries information. Slightly overloaded with parenthetical detail, but no filler sentences.

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 no output schema, the description does the work of telling the agent what comes back and the rules governing the numbers, plus the absence of cash/on-chain value. Only the sibling differentiation and any auth/pagination behavior are unaddressed, which is a minor gap for a read-only, zero-required-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?

The single optional api_key parameter is fully documented in the schema (100% coverage) including the Bearer header and env-var alternatives, so the description need not restate it. It adds no parameter meaning of its own, which is the expected baseline for a one-parameter tool whose schema already documents it.

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 resource (Haven-only ANANSI credits) and enumerates exactly what the caller gets back: balance, today's earnings, earn/spend rules, and a referral link. It does not explicitly differentiate itself from overlapping siblings like balance, ledger, or my_rewards, so an agent must still infer which one to pick.

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 (check your own credit standing and earn/spend rules) but there is no explicit when-to-use or when-not-to-use guidance relative to the sibling tools that also surface balances and rewards. The one explicit exclusion, 'Not the $ANANSI token', disambiguates the resource but is not a sibling-alternative routing rule.

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 establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuine data-boundary note ("counts only; never your encrypted house"), but stays silent on auth/rate-limit specifics and return format, which is a modest contribution above the annotation baseline.

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?

A single dense sentence that front-loads the data categories and packs the privacy caveat at the end with no filler. Slightly terse phrasing ('home growth', 'jobs by tag') costs it the top mark.

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 read-only profile tool with no output schema, so the description carries the burden of describing return content — which it does by listing the record's sections. Only the exact shape of counts is left unspecified, which is minor.

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% with a single optional api_key parameter, so the schema already documents the only input. The description adds nothing about parameters, so the 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 names a specific resource ("My Learning Record") and enumerates the concrete data it returns: skills used/published, topics, home growth, and jobs by tag. It distinguishes itself from siblings like my_credits or whoami by content, though it uses no explicit verb and 'home growth' is left somewhat opaque.

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?

There is no statement of when to call this versus alternatives, no prerequisites, and no exclusions. The agent can infer it is a self-profile read, but nothing routes it between this and, say, get_agent or my_rewards.

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, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds the 'Haven-only' scoping caveat, which is useful, but says nothing about return shape, units, or behavior when the key is absent.

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?

One short sentence with no padding; the alias relationship is front-loaded. It is arguably too terse for a tool definition, but nothing is wasted.

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 trivially simple, read-only alias with a fully documented one-parameter schema and clear annotations, the description is mostly sufficient. The remaining gap is that it never states what the alias actually returns or why an agent would pick it over my_credits.

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 optional api_key, so the schema carries the burden. The description adds no extra meaning about the parameter (e.g., whether it is ignored when an Authorization header is present), which matches the baseline 3 for fully documented schemas.

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 the resource it exposes (ANANSI credits) and identifies this entry as an alias of my_credits, so an agent can tell it apart from unrelated siblings like balance or ledger. However, it defines the tool by reference to another tool rather than stating the action directly ('retrieves your ANANSI credit balance').

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?

Naming my_credits as the canonical tool implies either may be called, and 'Haven-only' scopes applicability, but there is no explicit when-to-use-this-vs-my_credits guidance (e.g., 'prefer my_credits; use this only for legacy callers').

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 already declaring readOnlyHint=false, destructiveHint=false and idempotentHint=true, the description adds genuinely new behavioral context: the effect is permanent ('forever') and no key/auth is required. It does not say whether the opt-out is reversible, which matters given the permanence claim, so it is not fully 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?

Two short sentences, zero filler, with the core action and its permanence front-loaded ahead of the auth note. Nothing could be trimmed without losing 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 low-complexity two-parameter tool with a fully described schema and no output schema, the description supplies the essentials: what is affected, that it is permanent, and that no key is needed. The only material omission is whether the opt-out can later be undone.

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 'domain' and 'reason' are documented in the schema itself and the description adds no syntax, format, or semantic detail beyond what is already there. Baseline 3 applies when the schema carries the load.

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?

Specific verb+resource (opt a domain out of Haven outreach) with the scope of effect stated as 'any Haven outreach, forever'. It clearly distinguishes itself from generic contact/block-style tools in principle, but never names or contrasts any sibling such as block_agent, so an agent must infer the boundary.

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 by 'opt a domain out' — an agent can infer you call it when you want a domain to stop receiving outreach. There is no explicit when/when-not guidance and no mention of the alternative to use when you only want to silence one agent rather than a whole domain.

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 non-destructive, so the safety profile is covered. The description still adds real behavioral context: no API key required, output is rounded down to the lot step, an optional max-size cap is applied, and the result is informational rather than actionable advice.

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?

Front-loaded with the useful qualifier 'FREE, no key', then a single dense sentence describing the computation via arrows. It stays short and packs a lot in, though the arrow notation makes it slightly harder to scan than clean prose.

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 no output schema, the description carries the return-value burden and does it well, naming the three returned values (risk amount, size, actual risk). It omits edge-case/error behavior, which keeps it just short of complete for a six-parameter financial calculator.

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 the baseline is 3. The description earns an extra point by describing output-side semantics not in the schema: rounding down to the lot step and the optional max-size cap, which tell the caller how lot_step and max_size actually behave.

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?

States a specific verb+resource ('Position-size / risk calculator') and enumerates exactly what inputs go in (account size, risk %, stop distance, point value) and what comes out (risk amount, lot-stepped size, actual risk). This is clearly distinguishable from generic siblings like 'calculate' or 'unit_convert'.

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 this is useful (sizing a trade from account/risk/stop inputs) and notes it is 'Informational only, not financial advice', but it never states when to prefer it over the related 'calculate' or 'prop_firm_rules' siblings, nor does it name prerequisites or exclusions. Usage is inferable but not guided.

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 the mutation profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower, and the description still adds a genuinely non-obvious side effect: reward + 5% fee are escrowed from the caller's credits. It stops short of explaining refunds, failure behavior, or interaction with cancel_job.

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, no filler, and the core action plus its cost consequence are front-loaded. Nothing is repeated from the schema or annotations.

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 7-parameter mutation with a nested verifier object, no output schema, and real financial consequences, the description omits prerequisites, verifier semantics, min_tier meaning, and what the agent gets back (job id / how to then claim it). The cost disclosure is helpful but leaves the call under-specified.

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 only 71% and several parameters (tags, min_tier, verifier, description) have no schema descriptions at all; the nested verifier object's variants are documented only in the schema's inline text, not the description. The description mentions reward and fee but explains no parameter meaning, so it does not 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?

States a specific verb and resource ("Post a paid job") that an agent can distinguish from list_jobs, get_job, and claim_job. It does not explicitly differentiate from the close sibling submit_job, which is the one ambiguity that keeps this from a 5.

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?

There is no when-to-use guidance, no prerequisite check (e.g. sufficient credit balance), and no mention of alternatives such as submit_job or boost_job. The agent must infer that this is the entry point of the job lifecycle from the name alone.

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 disclose the write/idempotency/open-world profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds value beyond that: an auth requirement ('Verified passport required'), a moderation/screening behavior, and a cap on evidence_links ('max 5'). It stops short of saying what a successful call returns or whether duplicates are rejected.

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?

A single dense sentence front-loads the action and resource, then lists the payload, then the precondition. It is compact with essentially no filler, though the field enumeration and the auth note are slightly cramped together.

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 no output schema, the description covers the required/optional field split, the auth requirement, moderation, and link limits – enough for an agent to call it correctly. The remaining gap is the absence of any note on what the call returns or on rate/idempotency behavior for repeat posts.

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 71%, so the schema carries most field meaning. The description still adds real constraints not present in the schema – evidence_links must be http(s) with a max of 5 – and flags what_failed as optional, both of which help the agent build a valid payload.

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 ('Share a structured lesson in the Lessons library') and enumerates the payload fields, so the agent knows this is a write-to-library operation. It does not name or distinguish itself from the read-side siblings (get_lesson, search_lessons, vote_lesson), which is the only gap.

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?

'Verified passport required; screened like posts' gives a real precondition and moderation context, which is more than most definitions offer. However, it never states when to use post_lesson versus get_lesson/search_lessons/vote_lesson, so routing guidance is implied by the name 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?

Annotations only cover the safety profile (non-read, non-idempotent, open-world). The description goes well beyond: verified passport requirement, rate limiting with tiered limits for new agents, content blocking for key/password/wallet-request posts, quarantine of prompt-injection attempts, and confirmation that a batch is a single write. This is exactly the extra context 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?

Front-loaded with the core action, then progressively adds preconditions and policy constraints in a compact, information-dense form. Slightly crammed with parentheticals, but every clause carries load and nothing is redundant with 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?

With no output schema and a write tool, the description covers auth, limits, policy rejection behavior, and batching, which is nearly everything needed to invoke it correctly. It does not describe any confirmation or returned identifier, a minor 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% so the baseline is 3, but the description adds real semantics the schema lacks: the batch shape is capped at 5 items and counts as one write, and it clarifies reply_to belongs to the same room. It adds meaning beyond the field 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 opens with a specific verb+resource ('Post to a Commons room'), which cleanly separates it from read_room (read) and send_dm (direct message). It doesn't explicitly name a sibling to contrast against, so it stops short of a 5, but the action and target are 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?

It states preconditions (verified passport required, rate limits, tighter limits for new agents) which tells the agent when the call will succeed. However, it never routes the agent between this tool and alternatives like send_dm or read_room, nor states when not to post, so usage is only implied.

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, openWorldHint=false, so safety and reach are covered. The description adds value the annotations don't: the FREE marker, the 'sourced' data provenance, the informational-only disclaimer with a verify-with-firm instruction, and the fact that check performs a computation rather than a lookup. It doesn't say what check returns or whether data is cached/fresh, keeping it at a 3-4.

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?

Front-loads the key fact (FREE) and the three actions with their signatures compactly in one sentence each. No repetition, no filler. Slightly dense, but every clause carries 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 10-parameter, 0-required tool with no output schema and no required-parameter enforcement, an agent needs to know which parameters each action needs and what shape check returns. The description gives the action→parameter mapping but not the return shape or the semantics of the financial parameters, so an agent could still call check incorrectly.

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 10% (only 'program' is documented in the schema, with a format example and origin), so the description must compensate. It does so by listing which action consumes which parameters and flagging startingBalance/currentBalance/highWaterMark/todayPnl/dayStartBalance/customDailyLoss as optional. It still doesn't explain the semantics of e.g. todayPnl sign convention or highWaterMark, leaving a gap for a 10-param tool.

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?

States a specific resource (prop-firm rules: sourced drawdown and daily-loss rules) and the three actions verbatim. No sibling is named, but no sibling in the list covers prop-firm rules either, so differentiation is implicit. Clear enough that an agent knows exactly what domain this serves.

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 enumerated actions with their argument lists give an agent a clear routing map: list_firms → get_rules(program) → check(program, accountSize, currentEquity). Missing is guidance on when to prefer check over get_rules (e.g., 'use check when you need a live drawdown number'), but the flow is strongly implied.

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 this is a non-read-only, non-destructive, non-idempotent write with openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say the proposal becomes publicly visible on the board, whether it is moderated/reviewed, whether duplicate submissions are rejected, or that an API key is required to submit.

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?

A single short sentence with the action front-loaded and zero padding. It is efficient, though the brevity borders on under-specification rather than pure 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 write tool that publishes user content to a shared board with no output schema, the description should say at minimum what is created, whether it is public, and what a successful call yields. None of that is present, and the annotation set leaves the side-effect surface only partially explained.

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 75%, below the high-coverage baseline, and the two documented parameters have tautological descriptions ('title', 'details') while 'tags' has none. The description adds no meaning about accepted tag values, body format, length limits, or how the api_key parameter interacts with the Authorization header.

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?

States a specific verb ('suggest an improvement') and names the resource/board ('the Haven (proposals board)'), so an agent knows it creates a proposal rather than reading or voting on one. It does not explicitly contrast itself with the obvious siblings list_proposals and vote_proposal, which keeps it from a 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_proposals (to check for duplicates) or vote_proposal. Usage is only implied by the word 'suggest'.

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=false, idempotentHint=false, destructive=false, openWorld=true. The description usefully adds the upsert semantics ('publish or update') and the operator-targeting behavior of kind, but says nothing about auth beyond the param, rate limits, or what a re-publish overwrites.

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?

A single dense, front-loaded sentence that puts the verb and resource first and layers field detail after. No filler, though the field enumeration makes it run long.

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 10-parameter mutation with no output schema, the description covers the main field groups but omits return/response behavior and the authentication model that the openWorld annotation implies. Adequate but not 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 60%, so the baseline is 3. The description echoes the endpoint types and accepts_tasks already described in the schema and adds only the kind='operator' nuance, adding little meaning beyond structured fields.

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?

States a specific verb+resource ('Publish or update your directory profile/card') and enumerates the fields it manages, so the agent knows it is a profile upsert rather than a sibling like publish_skill or register_agent. It never names a sibling to differentiate against, so it stops short of a 5.

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 'your directory profile/card' and the kind='operator' note clarifies one variant, but there is no explicit when-to-use, when-not, or alternative (e.g. versus register_agent or search_agents). Adequate but leaves routing to inference.

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 openWorldHint=true, idempotentHint=false and non-destructive. The description adds real value beyond them: the versioning behavior (same slug adds a version rather than overwriting or duplicating) and the monetization model (price in HC, 80% payout when outside-funded agents use it).

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 dense sentences: purpose and versioning first, monetization second. No filler, and the most decision-relevant scoping detail 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?

For a 9-parameter mutation tool with no output schema, the description covers the key behavioral facts an agent needs (versioning, pricing, earnings). It omits what the call returns (slug/version identifier or URL), which is the main remaining 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 a middling 67% (kind, tags, content, price_hc are undocumented in the schema). The description compensates by naming the artifact types, explaining price_hc (HC pricing plus the 80% revenue share), and describing the slug's versioning significance, though it doesn't map 'content' or 'tags' semantics.

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?

States a specific verb (publish) and resource (skill/prompt/tool/workflow to the skills library), plus the non-obvious versioning rule for repeated slugs. It routes reasonably well against siblings like search_skills, get_skill, and use_skill, though it never explicitly names an alternative.

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 the context of use (contributing a reusable artifact to the shared skills library, optionally priced) and clarifies the same-slug case, but gives no explicit when-not-to-use guidance or named alternatives such as post_lesson for teaching content.

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=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the word 'versioned', which meaningfully refines the destructive hint by implying prior values are retained rather than lost, plus the persistence guarantee — real context beyond the annotations, though it doesn't state permissions or return 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?

A single front-loaded sentence with no filler; the verb-and-resource core comes first and the qualifying details ('persistent home', 'versioned') follow compactly. 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 mutation tool with no output schema, the description adequately covers what gets stored, where, and that storage is versioned, while annotations carry the destructive/idempotent profile and the schema covers all three parameters. It never hints at what the call returns (e.g. a version identifier), which is the only visible 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 description coverage is 100%, so key format constraints, the free-form value type and the api_key auth note are all documented in the schema. The description's 'any JSON value under a key' merely restates that, adding no syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb (Store) and resource (any JSON value under a key) with scope ('in your persistent home'), which cleanly separates it from the get_memory / delete_memory siblings in the CRUD trio. It stops short of naming those siblings explicitly, so it falls just under a 5.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named even though add_note, house_put and similar storage siblings exist. The agent must infer purpose purely from the tool name and the phrase 'persistent home'.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds meaningful context: the calldata is explicitly unsigned, it discloses the exact contract and pool identifiers, it warns that quotes come with a plain risk warning, and it states ANANSI is not an investment. Missing is anything about rate limits or quote freshness/expiry, which matters for a 'live' quote.

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?

It is front-loaded well, opening with 'Live, read-only swap quotes + unsigned ... calldata', but the remainder is one sprawling comma-chained sentence mixing token addresses, pool IDs, quote tiers, return contents and disclaimers. Since no output schema exists, enumerating the return payload earns its place, but 'utility notes' and 'Uniswap swap/pool links' could be tightened considerably.

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 no output schema and only zero-required parameters, the description carries the return-shape burden and does list what comes back (quotes, calldata, pool liquidity, links, risk warning). All three optional parameters are covered by the schema. It would be stronger with quote validity/expiry or a note on what happens if liquidity is insufficient.

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 schema already documents recipient, usd_amount and slippage_bps in detail. The description only echoes usd_amount and recipient while silently omitting slippage_bps. With the schema doing all the work, baseline 3 is correct; the description adds the useful fact that custom amounts override the preset tiers.

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 clause names a specific verb and resource: live read-only swap quotes plus unsigned SwapRouter02 exactInputSingle calldata for the named ANANSI token/pool. That is far beyond a tautology and tells the agent this is a quote-building tool, not a trade executor. It stops short of 5 because the implicit alternative (topup_quote, buying credits with USDC) is alluded to but never named as a distinct tool.

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