Agent Procurement Manager (APM)

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

With no annotations, the description carries the full burden. It usefully discloses the idempotency-like constraint (one answer per wallet per question) and that answers are persisted for aggregate insights, but it omits whether the answer is final/immutable, whether submission requires a signed transaction or gas, and whether any return value or confirmation is produced.

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

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

Two tightly written sentences with no filler, and the core action is front-loaded ahead of the constraint and persistence 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 mutation tool with no annotations and no output schema, the description covers the core action and the one-answer constraint but leaves important agent-facing questions unanswered: what the response looks like, whether the submission is on-chain or off-chain, and whether an answer can be changed.

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%; 'wallet' and 'question_id' have descriptions in the schema, while 'answer' has only a maxLength. The description adds no parameter-level meaning (e.g. expected answer format, allowed values, or where the question_id comes from), 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 names a specific verb and resource ('Answer today's rotating Swarm Signal market question'), so an agent can immediately tell what the tool does. It doesn't explicitly differentiate from the sibling 'leave_intel', which could be a similar submission-style tool, 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?

Usage is implied by 'today's rotating ... question', and the one-answer-per-wallet constraint is stated. However, there is no explicit when-to-use versus alternatives, no mention of what happens if the question was already answered, and no guidance on how to obtain the question_id.

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

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

With no annotations, the description carries the full burden and does well: it declares the tool is free, is non-transactional ("never executes a purchase"), and outlines the downstream payment flow (USDC on Base, eip155:8453, x402). What it omits is return shape/pagination and whether the listing is static or live, but the safety and cost profile are clearly disclosed.

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?

Purpose is front-loaded in the first sentence, and the remaining sentences are functional. The payment-workflow and Telegram-contact detail is somewhat beyond this tool's own scope and could live in a shared doc, but each sentence still earns its place for an agent navigating the API.

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 must convey return contents, and it does (8 categories plus due_diligence bundle, each with verified-supplier counts). It is complete enough to call correctly with no arguments, missing only response-format specifics.

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 the baseline is 4. The description adds value by enumerating the category identifiers that will appear in results, effectively documenting the value domain even though there is no input to describe.

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 ("List APM's 8 procurement categories") and even enumerates the categories, so an agent knows exactly what comes back. It also names the due_diligence bundle and the payload detail (verified-supplier counts), which cleanly separates it from siblings like apm_quote or apm_preview.

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 the tool is free and never executes a purchase, and routes the agent to apm_quote and POST /task?quote=<quote_id> when the goal is actually executing a purchase. It also names a human escalation path for bulk/unmatched needs. It stops short of explicitly contrasting itself with apm_preview or apm_register, so it's clear context without full alternatives coverage.

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

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

With no annotations, the description carries the full disclosure burden and does so well: it discloses that a human reads every message, that duplicates are stored once, that there is a rate limit of 3 messages per agent per day, that the operator visits left endpoints read-only, and that the tool is free and never executes a purchase. This is unusually rich behavioral context for a mutation-style tool.

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

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

The core purpose is front-loaded and the five-item enumeration is purposeful, but the definition is long and carries tangential material: the full x402/USDC purchase flow and the Telegram contact are useful for routing yet lengthen a feedback tool's definition considerably. Some trimming would improve signal density.

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, four-parameter tool with no annotations or output schema, the description covers when to call it, what makes a good message, and the operational constraints. The only meaningful gap is that it never indicates what the call returns (e.g., confirmation, id, or error shape), which matters slightly given there is no output schema.

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 all four parameters are documented in the schema, so the baseline is 3. The description adds modest context for the endpoint parameter ('our operator visits read-only agents who leave an address') and the caller_id linkage, but largely restates what the schema already explains.

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 concrete verb and resource: 'Free guest book: leave a message for APM's operator.' It also distinguishes itself from the purchasing path by stating it 'never executes a purchase' and points to apm_quote for that. It does not explicitly contrast with apm_categories, apm_preview, or apm_register, so sibling differentiation is partial rather than complete.

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 explicit when-to-use guidance by enumerating the five message categories the operator values, and it clearly states when NOT to use it by describing the alternative execution path (apm_quote -> POST /task with USDC on Base). Alternatives are named, though only for the purchase flow, not for the other sibling tools.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it states 'Executes nothing and charges nothing' twice, describes exactly what data is returned, and clarifies that actual payment occurs only later on Base via x402. This gives an agent a clear safety and capability profile.

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

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

The description is front-loaded with the preview's purpose and return values, then covers execution and operator contact. It is slightly long, but most sentences provide routing or safety information that 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?

There is no output schema, but the description enumerates the return fields (supplier names, unit prices, score breakdown, latency, success rate, selected supplier, customer price). It also explains the free preview versus paid execution flow, making the definition complete for this 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 description coverage is 80%, so the schema already documents most parameters. The description adds useful context about quote_id and execution, but quote_id is not an input parameter here, and it does not add meaning beyond the schema for task, input, category, caller_id, or max_budget.

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 precise verb and resource: a free supplier-selection preview that returns top-3 candidate suppliers and pricing details. It clearly distinguishes the tool from apm_quote by explaining that apm_quote provides the quote_id needed for execution.

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 describes when to use this tool versus the execution path: preview for free/non-executing selection, then apm_quote/post quote for a quote_id, then POST /task for purchase. It also routes edge cases such as questions or bulk needs to a human operator.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses the scoring weights, that the quote is free, that no purchase is executed, and the exact returned fields. It omits auth/rate-limit details and permission nuances beyond caller_id, which keeps it short of 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?

Purpose is front-loaded in the first clause, followed by return values, then the execution workflow and escalation contact. It is dense but every sentence contributes; slightly long but not padded.

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 naming the return fields (quote_id, chosen supplier, scored candidates, customer_price). With no annotations, it also covers the safety profile (free, no purchase) and the next step. Auth mechanics and error behavior remain 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 80%, so the schema already documents most parameters and a baseline of 3 applies. The description adds light context for caller_id (link to apm_register memory) and category (missing-category escalation), but says nothing about input or max_budget 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 verb and resource ('Get a free Agent Procurement Manager quote') and explains the mechanism: task classification, scoring of ≥3 verified suppliers, and pricing. It clearly separates the quote step from the separate execution step (POST /task), so an agent understands this tool does not purchase.

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

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

Provides explicit when-to-use context ('this tool is free and never executes a purchase') and the follow-on execution path (take quote_id, call POST /task, pay in USDC on Base). It also routes edge cases (questions, bulk needs, missing categories) to the Telegram operator. It does not, however, differentiate against the sibling apm_preview.

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

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

With no annotations, the description carries the full load and does so well: it discloses cost (free), that no wallet/payment is needed, that it never executes a purchase, the data-retention policy (category+price only, never task inputs), the idempotent upsert behavior on re-registration, and a human escalation path on Telegram.

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?

Core purpose is front-loaded and each early sentence earns its place. However, the paragraph describing how to execute a purchase via apm_quote/POST /task is a different tool's workflow, and the trailing Telegram/operator sentence adds promotional weight beyond what this tool strictly 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?

No output schema or annotations exist, but the description compensates by explaining what you receive (a caller_id) and the greeting/recall behavior. It stops short of describing failure modes (e.g., duplicate-name edge cases or invalid inputs), which would round out a zero-required-param registration 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 description coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description adds genuine semantic nuance for one parameter ('re-registering with the same name updates your existing card'), but nothing extra for contact, endpoint, looking_for, or referred_by.

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 ('register your agent and get a caller_id') and immediately frames the output artifact (caller_id) that other tools consume. It cleanly distinguishes itself from apm_quote/apm_preview by naming them as downstream consumers.

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 says to present the caller_id in future apm_quote / apm_preview calls, clarifies re-registration semantics (same name updates the card), and routes purchase execution elsewhere (quote_id → POST /task). Both the 'when to use' and the 'this is not for buying' boundary are stated.

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

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

With no annotations at all, the description carries the full burden, and it does disclose two valuable traits: the call is free and read-only (no cost, no mutation). It also hints at conditional coverage with 'catalog changes when history covers the period.' It does not say whether the address alone is sufficient authorization or what happens when no history exists.

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 no filler, and the resource list is front-loaded before the 'Free and read-only' qualifier. It is slightly dense—four resources packed into one clause with an embedded conditional—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 no output schema and no annotations, the description adequately covers what comes back at a category level and its access cost. The main remaining gap is what happens when the wallet has no history or history does not cover the period, which the description gestures at but does not resolve.

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 parameter with 100% schema coverage ('Your EVM wallet address'), so the schema already does the work and the baseline is 3. The description's use of 'your' reinforces self-scoping (no querying arbitrary wallets), but adds no format or validation detail 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 verb 'Read' is combined with four concrete resources (visit history, today's pulse, catalog changes, wishlist matches), which distinguishes it from the sibling tools such as answer_daily_question and claim_welcome_gift. The only weakness is that 'fresh pulse' and 'catalog changes' are domain jargon that an unfamiliar agent cannot fully decode, so the resource list is clear in shape but not entirely in substance.

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?

'Read your visit history' implies this is the go-to personal summary tool, and 'free and read-only' signals low-cost, safe invocation. However, there is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative for narrower queries, so the routing signal 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 no annotations, the description carries the full behavioral burden and largely fails: it never says whether this is a write/registration operation, that it collects identity data (name, wallet, contact), whether the claim is one-time or repeatable, or what the caller receives. Only the seller-only eligibility for gift C is disclosed.

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 action, then a compact semicolon-separated menu with no filler. The one long sentence is dense but every clause carries a distinct gift definition.

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

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

For a five-required-parameter submission tool with no annotations and no output schema, the description omits what a successful claim returns, how the claim code is obtained, and what is done with the personal and wallet data supplied. An agent cannot predict the outcome of calling 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 coverage is 50%, and the description directly compensates for the biggest gap by defining the opaque gifts enum values A–D. It also implicitly ties 'claim_code' to gift B and 'listing' to gift C, which the schema only hints at. Remaining gaps are 'name', 'contact', and the role/gifts interplay.

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 ('Claim a free welcome gift') and enumerates exactly what each claimable item (A–D) is, so an agent knows the payload it is selecting. It does not contrast itself with the apm_* siblings, but the operation itself 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?

Usage is implied through the gift menu and one conditional constraint ('C = sellers only'), which tells the agent eligibility for at least one option. There is no explicit when-to-use/when-not guidance, no mention of prerequisites such as having a prior quote, and no statement about what happens after claiming.

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

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

With no annotations, the description must carry behavioral disclosure. It usefully states that submissions remain quarantined and are never published verbatim, which is important context for a write-like tool, but it does not disclose review timelines, authentication expectations, duplicate handling, or what happens after submission.

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

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

The description is two tight sentences that front-load the core purpose and then add a key behavioral constraint. Every sentence earns its place and there is no unnecessary 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?

The description covers the tool's purpose and a notable data-handling behavior, which is useful given the absence of annotations and output schema. However, for a submission tool with four parameters and only half of them described in the schema, it remains incomplete regarding usage conditions and parameter meaning.

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 50%, so the description should compensate but does not. It vaguely references a 'structured market fact' but never explains the wallet, category enum, fact length limit, or optional URL parameters beyond what the schema already partially documents.

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

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

The description uses a specific verb and resource: 'Submit a structured market fact for manual corroboration.' It clearly states the tool's purpose, but it does not explicitly distinguish the tool from sibling names such as apm_feedback, which could also involve submitting information.

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

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

The description gives no explicit when-to-use guidance, prerequisites, or alternatives. 'For manual corroboration' implies the tool's purpose, but an agent must infer the appropriate context for submission rather than being told when this tool is the right choice.

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