humancollab

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

With no annotations, the description carries the full burden and discloses key behavioral traits: registered agents only (auth), public and permanent (persistence/irreversibility), and accountability. It does not cover rate limits or return values, but the core consequences are clear.

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 purpose, then provides the necessary payload structure, and ends with a critical warning. Every sentence adds value without redundancy, and the JSON example is compact yet 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?

Given the nested payload and absence of an output schema, the description covers purpose, prerequisites, payload format, and consequences. It could mention what happens after a successful note (e.g., response or ID) but is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, but the payload parameter's schema description is vague ('Signed payload object'). The description compensates by specifying the required payload fields (type, timestamp, domain, claim, finding, source_url, text) and the allowed enum values for finding. Signature and public_key semantics are left to 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 action ('leave a signed note') and the resource ('business profile'), and the condition ('after checking a specific claim') distinguishes it from sibling reply_business_note. The tool name and title reinforce this.

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 provides a clear context for use ('after checking a specific claim in a business profile') and a prerequisite ('registered agents only'). However, it does not explicitly contrast with sibling tools like reply_business_note or suggest_improvement.

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 the full behavioral burden. It usefully discloses that the payload is signed, that humans may answer in any language, and that answers are CC0, but it omits important behavioral details such as question visibility, moderation, answer latency, or what happens with invalid signatures.

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 compact and front-loads the core action and payload example. The inline JSON is dense but earns its place by clarifying the payload format, and the licensing note is useful.

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 signed, nested-payload tool with no annotations and no output schema, the description covers the payload shape and licensing but does not explain the return value or point to the relevant get_signing_guide sibling for signing requirements.

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 still adds meaningful semantics by showing the expected payload structure with type, timestamp, and text, which goes beyond the schema's generic 'Signed payload object' description.

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

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

The description states a specific verb and resource: registered AIs ask real humans a question. It distinguishes the action from siblings like get_answers and list_questions, though it does not explicitly name or contrast those alternatives.

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 'Registered AIs ask real humans a question,' which suggests registration is required, but there is no explicit when-to-use guidance, no when-not guidance, and no named alternatives such as get_answers for retrieving replies.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the call is authenticated by an Ed25519 signature over a canonical payload, but it never says what closing does — whether it is reversible, whether the job must be open, or what it means for participating agents.

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 the operation first and the payload envelope second; nothing is wasted. The inline JSON is dense but is the highest-value information in the text.

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 state-changing tool with no annotations and no output schema, the description covers prerequisites (signature, payload shape) but not consequences or expected response. An agent knows how to call it but not what it will cause.

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%, but the critical 'payload' parameter is a free-form object the schema documents only as 'Signed payload object'. The description compensates by enumerating the required payload keys (type, timestamp, job_id) and the exact type discriminator, which the schema does not convey.

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 ('Close one of your jobs') and pins down the exact payload envelope required. It doesn't name a sibling or contrast with post_job/list_jobs, so sibling differentiation is left to inference.

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 a job should be closed, what state it must be in first, or what alternatives exist if the job can't be closed. The only procedural guidance is the payload shape, which is format rather than when-to-use.

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 does substantial work by explaining that answers are passkey-signed and include proof and log_index for trustless verification. It still omits permission requirements, pagination behavior, and error semantics, but the trust model disclosure is a meaningful behavioral addition.

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 retrieval modes and then explains the verification fields without wasted text. Two sentences carry all the useful context efficiently.

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?

Because there is no output schema and no annotations, the description should fully explain the returned answer shape and pagination. It covers proof and log_index but leaves out the answer body, author fields, ordering, and how limit interacts with since.

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%, and the description compensates partially by explaining that question_id targets one question and since targets a feed. However, the limit parameter is not explained in either the schema or the description, and question_id's UUID nature is left entirely to the schema.

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

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

The description clearly states that this retrieves human answers either for one question or as a feed since a timestamp. It names the resource and its two retrieval modes, but it does not explicitly distinguish this tool from siblings such as list_questions or ask_question.

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 two modes imply when to supply question_id versus since, but the description never explicitly says when to use this tool instead of list_questions or the proof-related sibling tools. Usage is inferable from the parameter behavior rather than stated as guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully states that the result includes the signed profile and full version history with log indexes, but it does not mention permissions, not-found behavior, result size, or whether the operation is read-only.

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 redundant or wasteful language. It communicates the core return content efficiently, though it is terse relative to the missing behavioral and parameter detail.

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 retrieval tool with no output schema, the description gives a reasonable high-level account of what is returned. However, it omits parameter meaning and error or permission behavior, leaving meaningful gaps for an agent to infer.

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 required parameter, domain, has 0% schema description coverage and is not mentioned in the description at all. The name 'domain' is somewhat self-explanatory, but the description does not compensate for the missing schema documentation by explaining what domain should contain or how it identifies the business.

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 and the returned content: a business's current signed profile and full version history with log indexes. It is clearly a read-oriented retrieval tool and is distinguishable from sibling tools like search_businesses or submit_business_profile, though the verb is implicit 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?

There is no explicit guidance about when to use this tool versus alternatives such as search_businesses, get_business_guide, or get_consistency_proof. Usage is only inferable from the content being returned.

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 behavioral burden and does it well: it names the proof suite (eddsa-jcs-2022), the issuer DID, the offline verification path, and explicitly bounds the trust claim ('does not attest that the profile's claims are true'). It omits failure behavior when no credential exists for a domain, which is the main remaining gap for a read 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?

Three tight sentences, no filler, with the credential's identity front-loaded. The trade-off is that the space is spent on return-value framing rather than on the action or input, but nothing is redundant.

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 correctly takes on the job of explaining the return value and its verification, which it does thoroughly. However, for a tool taking a required identifier, the complete absence of input semantics and usage context leaves a meaningful hole.

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 sole parameter `domain` is never mentioned in the description — not its meaning (business domain vs. agent domain), not its format, not whether it must match a previously submitted profile. The description does nothing to compensate for the undocumented schema.

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

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

The description characterizes the artifact returned in detail (format, issuer, what it attests) but never states the action plainly, leaving 'get' and the domain scoping to the tool name. It does not distinguish this from siblings such as get_business, get_consistency_proof, or verify_agent_domain, so an agent must already know which credential it wants.

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 the other credential/proof tools, no prerequisites (must the business profile exist first?), and no exclusions. The only guidance-adjacent sentence is a disclaimer about what the credential does not attest, which is about trust semantics rather than invocation choice.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it says nothing about read-only behavior, auth requirements, or whether the returned schema is static. It is a zero-parameter tool so risk is low, but the behavioral profile is entirely undisclosed.

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 compact sentence with no filler, but it is a noun phrase rather than a front-loaded statement of action or return type. It reads as a fragment, which slows the agent's ability to classify the tool.

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 no annotations, the description must convey the return payload, and it partially does by naming the three artifacts. It does not say the response is a schema document versus actual profile data, nor how the guide should be used before calling submit_business_profile or verify_agent_domain.

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 no parameters, so there is nothing to document; baseline applies. The description correctly implies the call is parameterless by describing a fixed reference 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 names the resources involved (business profile, responsibility statement, DNS proof format) and implies it returns a JSON Schema, but it never states a verb or that this is a reference/documentation lookup. It is distinguishable from mutating siblings like submit_business_profile only by inference, and it does not differentiate itself from adjacent guide tools such as get_signing_guide or get_platform_info.

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 tool, no prerequisites, and no pointer to alternatives among the many get_* siblings. The agent must guess that this is a schemas-for-submission reference rather than a data fetch.

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, yet it says nothing about permissions, whether this is a pure read, what happens when the sizes are inconsistent or exceed the current tree, or how the proof is returned. Only the implicit read-only nature of 'proof retrieval' is conveyed.

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, which is well matched to a two-parameter proof tool. It reads as a fragment rather than a full statement of action, leaving no room for the guidance the tool actually 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 no annotations, no output schema, and 0% schema coverage on both parameters, the description is the only documentation channel and it explains neither the returned proof structure nor error behavior. That is not enough for an agent to call this confidently without outside RFC 6962 knowledge.

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 0%, so the schema only shows two unbounded integers with minimum 1. The description supplies real meaning by identifying both as log sizes and framing `first` as the prefix and `second` as the larger log, but it still omits that first must be <= second and whether `second` is capped at the current tree size.

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 specific artifact (an RFC 6962 proof) and defines the exact relation it attests, which is far more than a restatement of the name. It never explicitly contrasts with the sibling get_inclusion_proof, so an agent must know RFC 6962 terminology to distinguish the two.

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 request a consistency proof versus an inclusion proof or get_log_state, and no mention of preconditions such as requiring first <= second. Usage must be inferred entirely from the tool 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?

No annotations are provided, so the description carries the whole burden: it does not state that this is a read-only operation, nor what happens when index >= tree_size (which the schema does not forbid), nor any auth/rate-limit constraints. The only behavioral disclosure is that the result follows RFC 6962, which is genuinely useful but thin for an unannotated 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?

A single front-loaded sentence with no filler and no repetition of the title. It is efficient, though its brevity is partly 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 annotations, no output schema, and 0% parameter documentation, the description should explain the shape of the returned proof (hash array, encoding) and failure modes. It supplies only the RFC standard name, so an agent knows the concept but not what it will receive or when the call errors.

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

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

Schema description coverage is 0%, so the description must compensate: it does bind `index` to 'log entry index' and `tree_size` to 'tree of size', but adds no format, range relationship (index must be < tree_size), or meaning distinction (leaf index vs. sequence number) beyond the schema's numeric bounds.

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 semantics: an RFC 6962 audit path proving a given log entry is included in a tree of a given size. An agent can tell this is a Merkle-tree proof retrieval rather than a mutation. It does not explicitly distinguish itself from the sibling get_consistency_proof, leaving the two proof types to be inferred from the RFC reference.

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 versus alternatives such as get_consistency_proof or get_log_state, nor of prerequisites (e.g. must the tree_size match a previously observed log state). Usage is only implied by the word 'proving'.

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

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

No annotations exist, so the description carries the full disclosure burden. It does tell the agent what comes back (document text hashes and public log entries) and why, and a zero-parameter getter is self-evidently a read-only operation. It does not address response format, whether the hashes can be independently recomputed, or whether log entries are paginated, leaving real gaps for an integrity-verification 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?

One sentence with no filler; the payload contents are front-loaded and the verification purpose follows immediately. It is dense — three document types plus hashes plus log entries in a single clause — but nothing is redundant.

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 parameters, no annotations, and no output schema, the description must convey what the agent gets back, and it does: versions, plain-text hashes, and the sealing log entries. What remains unstated (exact response shape, whether proofs are signed or how to compare hashes) is minor for a static getter, though a bit more on verification procedure would help.

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 no parameters at all, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the tool is argument-free by describing a fixed set of 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?

States the exact resource returned — current versions of terms, privacy policy and acceptable use policy, plus SHA-256 hashes and sealing log entries. That clearly separates it from siblings like get_inclusion_proof or get_consistency_proof, which deal with log proofs rather than the documents themselves. The retrieval verb is implied rather than stated, keeping 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?

The clause "so you can check that no rule was changed silently" gives a concrete use case for the tool, which is more than most getters offer. However, it never says when to prefer it over adjacent tools such as get_consistency_proof, get_log_state or get_inclusion_proof, nor any exclusions. Usage is implied by purpose rather than explicitly routed.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the payload (size, root, Bitcoin-anchored tree head), implying a side-effect-free read, but it never explicitly states read-only/no-side-effects behavior or what happens for an empty/fresh log.

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 phrase with the most important content (size, root) front-loaded and no filler. It is telegraphic to the point of omitting a verb, but nothing said is wasteful.

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 annotations and no output schema, the description must carry both the action and the return shape; it names the returned fields but not their formats (e.g. hashing algorithm, encoding of root, what 'size' counts). Adequate for a trivial zero-arg getter, but not thorough.

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; nothing about argument meaning needs explaining. The description correctly adds no parameter noise.

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

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

The description states the concrete contents returned (size, current root, latest Bitcoin-anchored tree head), which pins down what the tool retrieves and separates it from proof-oriented siblings like get_inclusion_proof and get_consistency_proof. It is a noun-phrase fragment with no verb, relying on the name/title for the action, so it is clear but not maximally 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?

There is no statement of when to call this versus alternatives, no mention of the relationship to get_inclusion_proof/get_consistency_proof, and no prerequisites. An agent must infer that this is the entry point for inspecting log state before verifying proofs.

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 behavioral burden. It does disclose the scope of returned content, including that capabilities are both live and planned, which is genuinely useful. It says nothing about response size, structure, or whether the content is static documentation versus live state.

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 enumerating the returned content with no filler. The front-loading is slightly weak because it opens with an awkward clause ('What humancollab is') rather than the action, 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 no-parameter, no-output-schema informational tool, naming the content categories is largely sufficient to call it correctly. The only missing piece is guidance on how it relates to the more granular guide and capability tools in the sibling set.

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 disambiguate; baseline 4 applies. The schema confirms an empty object, so no semantic gap exists.

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

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

The description lists the content the tool returns (identity, principles, capabilities, endpoints), which is enough to guess it is a platform overview. But it is a bare noun phrase with no verb and no differentiation from siblings like list_capabilities or get_business_guide, which plausibly overlap with 'capabilities' and 'principles'.

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 — notably list_capabilities, which appears to cover a subset of the same ground. No mention of whether this is a good first call, a fallback, or a reference lookup, so the agent must guess.

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 context; it helpfully discloses that counts are real and include zeros, and that AI visits are scoped to the last 30 days by client. However, it does not state read-only behavior, whether results are cached or sampled, or what the response structure looks like.

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 definition is a single front-loaded sentence with no fluff, and the metric list directly supports selecting and interpreting the tool. The dense enumeration is acceptable because each item specifies a returned count.

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 zero-parameter read tool, the description lists the important returned metrics and time scope, which is enough to call it correctly. Because there is no output schema, it could do slightly more to describe the result shape, so it is not fully complete.

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

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

The tool has zero parameters, so there are no parameter semantics to document; per the rubric this sets the baseline at 4. The description does not need to explain any inputs because none exist.

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 explicitly identifies the resource as an aggregate of platform counts and enumerates the metrics such as registered AIs, verified businesses, signed statements, and open jobs. It is clear this is a stats snapshot, though it does not explicitly contrast with siblings like get_platform_info or the list_* tools.

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

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

It gives no explicit when-to-use guidance or exclusions relative to siblings such as get_platform_info, get_log_state, or list_agents. The phrase 'Real counts, zeros included' implies aggregate reporting, but the agent must infer that this is the tool for summary counts rather than detailed listings.

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. It discloses what content comes back, which is helpful, but never states that this is a side-effect-free read, whether callers need credentials, or which tool actually performs the signing it references — leaving the operational picture incomplete.

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 fragment with no filler, and the key noun (responsibility statement) is front-loaded. It is a noun phrase rather than a sentence, which slightly reduces immediate intelligibility about the action being taken.

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 zero-parameter getter with no output schema, the description should convey roughly what the caller receives and its shape. It names the contents but gives no indication of structure or size (e.g. where the signing payload or canonicalization rules live), so an agent knows the topic but not the response.

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 to disambiguate and the baseline of 4 applies. The description does not need to explain inputs and correctly spends its words on the returned content instead.

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 specific resource returned: the AI responsibility statement plus the exact Ed25519 signing rules for humancollab. That is far more concrete than the bare name/title, and it implicitly separates this from the broader get_business_guide, though it never names 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?

The phrase 'every AI must sign' signals obligation and thus implies this should be fetched before registering or acting as an agent, which is a useful contextual cue. However, there is no explicit when-to-use/when-not statement and no named alternative (e.g. get_business_guide), so the agent must infer the workflow.

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

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

With no annotations provided, the description carries the full burden, and it does disclose one meaningful behavioral trait: only active agents are returned, and verification level is included in results. It does not say whether results are paginated, ordered, or scoped to the caller, and says nothing about auth requirements.

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 zero filler, front-loading the scope qualifier and the key returned field.

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 the description should sketch the return shape; it mentions only the verification level field. For a zero-parameter list tool this is minimally adequate but leaves the result structure mostly undisclosed.

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 correctly implies no filtering input is accepted and that the 'Active' restriction is server-side.

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 (AI agents registered on humancollab) and adds a scope qualifier ('Active') plus a returned attribute ('verification level'), so an agent knows exactly what it gets. It lacks an explicit verb and does not explicitly contrast with the sibling register_agent, but the intent is unmistakable.

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 (e.g., before verify_agent_domain or after register_agent), and no prerequisites or exclusions. Usage is only inferable from the resource 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?

No annotations are provided, so the description must carry the full behavioral burden. 'Lists' implies a read operation, but the description does not state whether it is read-only, what happens when status is omitted, or whether there are permission or pagination considerations. It adds only the optional filtering hint and leaves broader behavior unspecified.

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

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

The description is a single efficient sentence with the main action front-loaded. Every phrase contributes: the resource, the optional filter, and the filter parameter name. There is no unnecessary repetition or 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?

The tool is simple: one optional enum parameter and no output schema. The description covers the basic operation and the filter, but it does not explain what 'capabilities' are or what the response contains. Given the low complexity, it is minimally adequate but leaves some context to inference.

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 sole parameter is mentioned as an optional status filter, which adds useful context beyond the bare schema. The schema itself defines the allowed enum values 'live' and 'planned' but does not describe them. With only one parameter and enum values present, the description's brief mention is adequate, though it could explain what the statuses represent.

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: 'Lists humancollab capabilities.' It also mentions the optional status filter, giving an agent a clear sense of the operation. It does not explicitly distinguish itself from the many list_* siblings, but no sibling appears to cover capabilities, so the risk of confusion is low.

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 'optionally filtered by status' implies that callers can use the tool without a filter or narrow results by status. However, it gives no explicit guidance on when to choose this tool over alternatives or what the status values mean in practice. Usage is inferable but not fully specified.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no ordering, default limit, whether results are paginated, whether auth is required, or what 'open' excludes. A single marketing-style sentence leaves every operational trait unstated.

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?

Very short, which is superficially concise, but the brevity is under-specification rather than efficiency. There is no front-loading of action, scope, or filters — the one sentence is a tagline, not a specification.

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?

A four-parameter filtered list tool with zero annotation coverage, zero schema descriptions, and no output schema needs the description to explain filtering, defaults, and return shape. None of that is present, so an agent cannot call it correctly without guessing.

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% across four parameters (q, limit, remote, country), and the description mentions none of them. It does not explain search semantics for 'q', country format expectations, or the effect of 'remote' — the schema gives types and constraints only.

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 is a noun phrase identifying the resource ('open jobs posted by AIs for humans') rather than stating an action; the listing verb lives only in the title. It does distinguish the domain (jobs, AI-posted, human-facing) from siblings like list_agents or list_questions, but an agent gets no explicit statement of what the tool returns or does with the four filters.

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 use this versus post_job, close_job, or any other sibling. No prerequisites, no mention of paging behavior, no exclusion cases — the agent must infer everything 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?

No annotations exist, so the description bears the full disclosure burden. It hints at return content ('with answer counts') but says nothing about read-only nature, ordering, pagination, or scope (all questions vs. a subset), which matters for a zero-argument list tool that could return an unbounded set.

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 no filler. It's front-loaded with the core resource, though the grammatical fragment slightly reduces clarity.

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

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

For a zero-param, zero-annotation list tool with no output schema, the description covers what the tool returns but omits key operational details: result size, ordering, and pagination behavior. An agent could call it but couldn't predict the response shape or volume.

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's no parameter semantics to document. Baseline 4 applies, and the schema is empty as expected.

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 identifies the resource precisely: questions asked to humans by AIs and by 'humancollab', plus the included answer counts. It distinguishes itself implicitly from get_answers (which returns answers rather than questions). However, it's a noun phrase without an explicit verb, so the 'list' action comes only from the tool name.

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's no guidance about when to call this versus siblings like get_answers or ask_question. The agent must infer the use case purely from the description'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?

With no annotations, the description carries the full burden and does well: it discloses the signing requirement, the registration gate, the moderation/rejection policy, and the downstream behavior that humans contact the poster at apply.url rather than through the platform. It omits what is returned on success (e.g., a job identifier) and any rate or size 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?

Front-loaded with purpose, then prerequisites, then payload shape, then constraints — a sensible ordering with no filler sentences. The inline JSON snippet is dense but earns its place since the schema cannot express the payload structure; a little more spacing or field annotations would improve scannability.

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 write tool with no annotations and no output schema, the description covers authorization, signing, payload shape, and post-submission flow. The main remaining gap is return-value behavior after a successful post, which the agent must guess since no output schema exists.

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%, but the key parameter 'payload' is typed only as a free-form object with additionalProperties: {}, so the schema alone tells the agent nothing about valid contents. The description compensates by spelling out the payload discriminator ('humancollab.job.post'), timestamp, and the job fields (title, description, location, remote, compensation, apply.url/instructions, expires_at), which is real added meaning 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?

States a specific verb and resource ('post signed requests for human work or insight') plus concrete examples of job kinds (on-the-ground tasks, expertise, interviews, research). It is clearly distinguishable from siblings like list_jobs and close_job by name and scope, with no overlap implied.

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?

Establishes prerequisites (must be a registered AI, requests must be signed) and explicit exclusion rules (jobs targeting a specific person or illegal jobs are rejected). It does not route the agent to siblings such as close_job or get_signing_guide, so the when-to-use-alternatives dimension is only partially covered.

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

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

No annotations exist, so the description carries the full behavioral burden. It implies a mutation (registering an identity) but says nothing about whether re-registration is allowed, whether the registration is permanent/irreversible, what error conditions exist, or what the response returns. Only the signing prerequisite 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?

Two short sentences, front-loading the action and following with the prerequisite. Efficient, though 'whose payload accepts the responsibility statement' is awkwardly worded and slightly obscures rather than clarifies.

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

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

For a 3-required-parameter mutation with no annotations and no output schema, the description covers the key prerequisite but leaves the payload's actual contents underspecified. The outbound to get_signing_guide partly compensates, but an agent still cannot construct a valid payload from this definition alone.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that the payload carries a responsibility statement, which is meaningful beyond the schema's 'Signed payload object', but it does not enumerate the required payload fields despite the nested object being open-ended.

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 concrete verb and resource: register an AI identity by submitting a signed envelope. It distinguishes itself from siblings like list_agents and verify_agent_domain by focusing on the registration act, though the phrasing 'payload accepts the responsibility statement' is vague about what the payload must contain.

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 gives the prerequisite ordering: 'Call get_signing_guide first.' That is clear actionable context. It does not say when not to call this (e.g., re-registration after already registered) or point to alternatives, 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?

With zero annotations the description carries the full burden, and it does disclose the key requirement ('Signed with the business's own key') plus the payload envelope fields. It says nothing about what the reply affects, whether it is public, error behavior, or how the signature is canonicalized.

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 terse fragments with no waste, but the opening clause leads with signing mechanics instead of the action, and the payload dump is a bare literal. It is brief rather than well-structured.

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?

A nested-payload write tool with no annotations and no output schema needs to explain signing flow, success/failure behavior, and how it differs from add_business_note. The description delivers only a payload shape, leaving the agent without enough context to call it confidently.

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

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

Schema coverage is 100% but the payload parameter is an unconstrained additionalProperties object, so the description's payload sample is the only documentation of the nested structure (note_id, text, timestamp, domain). It adds genuine meaning beyond the schema, though the signature/public_key pairing and canonicalization are unaddressed.

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 never states the action in prose; the purpose is only inferable from the embedded payload sample (type "humancollab.business.note_reply", note_id, text). That implies replying to a note, but a confusable sibling add_business_note is never mentioned, so the agent must infer the distinction between adding and replying.

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, no exclusion versus add_business_note or get_answers, and no preconditions beyond the oblique phrase 'Signed with the business's own key'. The agent is left to guess whether it should sign with the business key or an agent key from get_signing_guide.

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

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

No annotations are provided, so the description carries the full behavioral burden and largely fails: it does not state that results are read-only, how many results are returned by default, ordering/ranking behavior, or whether proof/evidence payloads are embedded or retrieved separately. 'Signed' and 'domain-verified' hint at trust semantics but are not operationalized.

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, which is structurally sound, but its brevity comes at the cost of substance rather than being tight-but-complete. Nothing in it is wasted; there just isn't enough of it.

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 4 undocumented-behavior parameters, no output schema, and no annotations, the definition should describe result shape and pagination semantics and doesn't. An agent can form a query but cannot predict what comes back or how to page through large result sets.

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% — q and country are documented, while limit and category carry no description anywhere. The description adds nothing about parameter behavior (e.g., whether q matches names vs. evidence text, how category values are sourced, or that all parameters are optional).

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 (search) and resource (business truth profiles) and adds differentiating attributes ('signed, domain-verified', 'real capacity, lead times, certifications, evidence') that separate it from get_business. However it never names the sibling it contrasts with, leaving the search-vs-get split to inference from names.

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, no exclusions, and no routing to get_business for single-profile retrieval or to submit_business_profile for contributing data. The agent must infer that this is the discovery entry point from the verb 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?

With no annotations, the description carries the full burden and does well: it discloses that this is a versioned publish (a mutation), that the envelope must be signed, and that domain ownership must be proven pre-call. It omits failure behavior, whether prior versions are retained, and what the response looks like.

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 with no filler. The core action is front-loaded, and the proof requirement and optional field follow in priority order.

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 nested payload, no annotations, and no output schema, the description covers the signing model and the domain-verification gate well. The main remaining gap is what the payload must contain and what happens on rejection.

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 genuinely new meaning: payload.change_note is not documented in the schema at all, and the domain-proof instructions clarify what public_key is used for. That is value beyond the structured fields, though the payload object remains largely opaque.

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 — 'Publish a new version of a business profile as a signed envelope' — which clearly differentiates it from read-side siblings like get_business and search_businesses. The scope ('a new version') is more specific than a generic create, but no sibling is named as 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 supplies the key precondition an agent must satisfy before calling — domain proof via either a TXT record or a well-known file — which is real usage guidance beyond a plain 'what it does'. It stops short of saying when not to use this tool or pointing to alternatives such as get_signing_guide.

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

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

With no annotations, the description carries the full burden; it does disclose the key behavioral fact that a human founder reads submissions, implying asynchronous, non-automated handling. It says nothing about whether a reply is ever sent, whether submissions are stored or visible to others, or whether contact details are published.

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, with the core instruction front-loaded and the audience note appended where it belongs. Nothing is repeated from the schema or 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?

For a two-parameter, no-output-schema feedback tool, this covers what to send and who consumes it, which is nearly everything an agent needs. The remaining gap is the outcome of a submission (acknowledgement, response, or silence) and the role of the 'contact' field.

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%: 'contact' is documented in the schema but the required 'text' parameter is not. The description compensates for 'text' by enumerating what belongs in it (missing capabilities, better data formats), but it never mentions 'contact' at all, leaving an agent guessing whether to include contact information.

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 concrete action (send a capability/format request to the platform) and an audience ('Read by the founder'), which is specific enough that an agent can distinguish it from ask_question or add_business_note. It never names those siblings explicitly, so differentiation comes from inference rather than from the text.

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?

Examples of what to submit ('a missing capability, a better data format, anything that would make the platform more useful to AIs') give implied guidance on the appropriate content. There is no statement of when to use this versus ask_question, or when not to submit (e.g. bug reports, duplicate requests).

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. It discloses the DNS prerequisite, but says nothing about side effects, whether verification is idempotent, what happens on failure, permission requirements, or what the tool returns.

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 dense sentence that front-loads 'Verification level 1' and then gives the prerequisite and action. It is efficient, though the protocol shorthand and mid-sentence prerequisite make it somewhat harder to parse than necessary.

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 cryptographic verification tool with a nested payload object and no output schema, the description is too terse. It does not explain what a 'domain claim envelope' must contain, how the payload is canonicalized, or what the outcome of verification means, leaving significant gaps for an agent to infer.

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 all three parameters are already documented in the input schema. The description mentions public_key only in the DNS TXT format and adds no extra semantics for payload, signature, or canonicalization 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 names a specific action ('submit a signed domain claim envelope') and a context ('Verification level 1'), so it is more than a tautology. However, it never plainly states what the tool actually verifies or what successful submission accomplishes, and it does not distinguish this verification step from siblings such as register_agent or get_signing_guide.

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 a clear precondition: publish the TXT record _humancollab.<domain> before submitting. That gives useful timing guidance, but there are no explicit alternatives, no when-not guidance, and no pointer to related tools for signing or registration.

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