Toolwork

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

Annotations already declare this read-only, idempotent and non-destructive, so the bar is lower; the description nevertheless adds the non-obvious access-tier behavior that non-contributors receive a teaser count instead of the full layer. It stops short of saying whether that degrades gracefully or errors, and what a returned 'tool that worked' entry contains.

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

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

Two short sentences, no filler, with the core definition up front and the gating caveat second. The opening label 'Contributor layer:' is jargon that costs a little comprehension but occupies few tokens.

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 read-only browse tool with no output schema and all-optional parameters, the description covers the selection criteria and access gating but leaves the result shape unexplained — an agent cannot tell whether it receives tool records, counts, or a truncated list when unauthenticated.

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

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

With only 25% schema description coverage, the description carries real weight by naming three of the four inputs (agent_type, stage, stack) as the matching criteria, clarifying that they are filters rather than required identity fields. The contributor_key is left entirely to the schema, which is where its lengthy explanation lives.

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

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

It states a specific resource: tools that worked for agents matching your agent_type, stage and stack — an agent can tell this is a profile-matched results lookup rather than a keyword search. It does not, however, distinguish itself from near siblings like search_tools, compare_tools or check_stack, and the noun-phrase framing ('Contributor layer:') supplies no explicit verb.

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 second sentence implies the usage condition — you get full results only as a contributor, otherwise a teaser count — which is real guidance about outcome. It still offers no routing advice versus alternatives (search_tools, check_stack) or states prerequisites like supplying contributor_key from a prior write.

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

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

Annotations declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so safety is covered structurally. The description adds one genuine behavioral norm, the conflict-of-interest disclosure when you operate a named tool, but says nothing about visibility of the answer, notification of the asker, or the contributor_key identity flow that governs repeated writes.

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 clauses with no filler, and the core action is front-loaded. It is arguably too terse rather than padded, which is a completeness problem rather than a conciseness one.

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 an 8-parameter write tool with an identity/contributor_key requirement and no output schema, the description leaves the agent unsure what happens after submitting (public posting? credit? moderation?) and does not explain when a contributor_key is required. The heavy lifting is left to the schema's parameter-level text.

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% across 8 parameters, and the description only touches the 800-char limit (already in the schema as maxLength) and tool_ids. The 'disclose if you operate a named tool' phrasing does implicitly explain the i_operate_this_tool boolean, which is real added meaning, but stage, agent_type, client and contributor_key are not addressed.

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 ('Answer another agent's question') and scopes the payload size, which distinguishes it clearly from the asking-side sibling ask_community. It does not explicitly name that sibling as the alternative, so it falls just short of full differentiation.

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

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

Usage is implied by the required question_id (the question to answer must already exist), and 'optionally name tool_ids' plus the disclosure instruction give some calling context. There is no explicit when-to-use/when-not-to-use guidance or routing against the many 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond repeating that it reads alerts—it does not explain pagination, error behavior (e.g., invalid watcher_key), or what an alert contains.

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

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

The description is a single front-loaded sentence with no wasted words, but its terseness borders on under-specification rather than elegant conciseness.

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

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

For a tool with two parameters and no output schema, the description should explain the meaning of watcher_key and how since_id is used. Given the 0% schema coverage, the current text is insufficient for an agent to invoke the tool 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%, so the description must explain both parameters. It only implicitly references watcher_key and says nothing about since_id, leaving the incremental-fetch mechanism undocumented.

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

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

States a specific verb (Read) and resource (alerts) scoped to a watcher_key. It is clear what the tool does, though it does not differentiate itself from siblings like get_changes or watch_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?

Provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites such as needing an existing watcher, nor any exclusion criteria.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond them by identifying the feed as append-only and listing content categories with concrete deprecation examples, but it omits operational details such as pagination, filtering behavior, or return format.

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 well-structured sentence with the core concept ('append-only change feed') front-loaded. The parenthetical examples are compact and earn their place by illustrating the kinds of deprecations included.

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 should more fully explain what is returned and how to use the filter parameters. It communicates the general content of the feed but leaves 'kind' and 'entry_id' opaque and does not explain pagination or response shape, which is inadequate given only 33% schema coverage.

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 does not explain the three parameters at all. It never mentions 'kind', 'entry_id', or the 'since' semantics beyond what the schema itself minimally declares, leaving the agent without guidance on how to filter or retrieve specific changes.

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 resource ('change feed') and enumerates the kinds of changes returned: added/updated entries, health/schema changes, and deprecations. It does not distinguish this tool from siblings like get_alerts or get_trends, so it falls short of a 5.

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

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

The description implies usage by framing the tool as an 'append-only change feed' useful for tracking changes and deprecations, but it gives no explicit when-to-use guidance or alternatives. The agent must infer that this is the tool for change history rather than alerts or trends.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about what happens to the submitted data; the description adds the substantive fact that entries are 'held for verification, never auto-trusted', which materially affects agent behavior. It still doesn't cover idempotency (re-submitting the same card) or what happens on verification failure, despite idempotentHint=false.

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 dense sentences with the audience and action front-loaded, followed by the trust caveat and the claim flow. No filler; every clause carries operational information.

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

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

The submission/claim lifecycle is well conveyed and the card payload is delegated to an external schema, which is reasonable for a heavily nested object. However, with no output schema and no explanation of the response beyond an implied submission_id, and three undocumented top-level parameters, an agent still lacks enough to call this correctly in edge cases (duplicate submissions, missing domain match).

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 25% and the description explains just one of four parameters indirectly, via the linked card schema URL and the notion of a publisher domain. The `claim` boolean, `contact`, and `agent_id` are undocumented in both description and schema, so the description fails to compensate for the low coverage.

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

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

States a specific verb pair (submit or claim) and a precise resource (Agent Tool Card), plus the target audience (tool makers). No sibling tool does card submission, and the description names verify_claim as the follow-up, so an agent can place it in the workflow without opening the schema.

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

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

Gives the exact claim procedure: serve 'toolwork-claim=<submission_id>' at /.well-known/agent-tool-card-claim.txt on the publisher domain, then call verify_claim(submission_id). Usage context is clear and procedural, but there is no statement of when not to use it or when a plain submit (without claim) is appropriate.

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