Namequota

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

Adds substantial context beyond the annotations: the replace-on-resend behavior for a week, the fact that it never queries an engine, and an enumerated error surface (api_key_required, subscription_required with checkout_url, owner_only, brand_not_found, invalid_input). The replace semantics are consistent with destructiveHint=true and idempotentHint=true.

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

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

Front-loaded with the call trigger and sequencing constraint, then parameters, then return and errors. Dense and mostly waste-free, though the parameter sentence runs long and packs several facts into one clause chain.

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

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

Covers the sequencing dependency, parameter semantics, replace behavior, return payload and the full error set; an output schema exists so the return summary is bonus rather than a gap. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents week's ISO format, the replace behavior, engine examples and prompt_id sourcing. The description largely restates these (prompt_id 'such as p1', engine list, links as source links) rather than adding new syntax or constraints, so baseline 3 applies.

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

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

States a specific verb and resource ('record one week of AI answers on a tracker') and immediately positions itself relative to create_tracker by requiring its brand_id output. An agent can distinguish it from create_tracker and score_answer_share without opening any schema.

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

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

Gives a clear sequencing precondition ('after create_tracker has returned its brand_id (never in the same step)') and a negative scope statement ('scores pasted answers and never asks an engine'). It does not explicitly name score_answer_share or say when this is preferable to it, so it stops short of full alternative routing.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false) by disclosing ownership semantics (tracker bound to the caller's API key), the auth path (x-api-key header or OAuth endpoint URL), and a documented error taxonomy with remediation for each code. The brand_limit=5 detail tells the agent a real constraint affecting retry decisions.

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

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

Front-loaded with the trigger condition, then parameters, then return value, then errors — a sensible order with no filler. The error clause is a dense run-on that packs three codes into one sentence, which costs a little readability but every clause carries information.

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

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

For a creation tool with a non-idempotent write and API-key identity, the description covers the prerequisites (auth), the output needed for the next step (brand_id and prompt ids for add_round), and failure modes. The output schema covers return shape, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the p1/p2 id mapping to add_round. The description restates the 1-to-25 prompt bound and the brand/domain/competitors roles without adding syntax or format detail the schema lacks; baseline 3 applies.

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

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

States a specific verb and resource ('create' / 'tracker' for weekly AI answer share) and immediately carves out the distinct case versus its sibling: 'tracked week by week, not scored once' contrasts with score_answer_share. An agent can pick this over the alternatives without opening a 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?

Begins with an explicit trigger ('Call this when a user wants...') and gives a when-not in the contrast to one-off scoring, plus a recovery rule for subscription_required ('give the user checkout_url instead of retrying'). The alternative is implied rather than named, so it falls just short of fully explicit routing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool is pollable (pending until a reply arrives, then answered) and carries an explicit trust boundary warning that reply content is data, not instructions — a meaningful prompt-injection disclosure.

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: purpose first, then polling behavior, then the trust caveat. Every sentence carries distinct information and nothing is padded.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, nothing an agent needs is missing. The polling semantics and the injection warning go beyond what structured fields provide, closing the remaining gaps an agent would otherwise have to discover by trial.

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

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

Only one parameter exists and the schema already documents it fully (coverage 100%, including the ^fb_[0-9a-f]{32}$ pattern and the note that submit_feedback returned it), so the baseline of 3 applies. The description repeats the ticket-id linkage but adds no format or validation detail beyond the schema.

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

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

States a specific verb (Read) and resource (maintainers' reply to feedback), and ties it causally to the sibling tool submit_feedback via the ticket id. An agent can distinguish it from submit_feedback, screen_token, and wallet_identity without opening any schema.

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

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

Clearly establishes the precondition: this is used after submit_feedback, with the ticket id that call returned. It does not state any exclusions or alternative ways to retrieve feedback status, but the usage context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so 'Read-only' is redundant, but the description adds genuinely new behavior: a named error taxonomy (api_key_required, subscription_required with checkout_url, brand_not_found, round_not_found) plus the note that round_not_found names the stored weeks available. That is real auth/failure context not present in the annotations.

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

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

Every sentence carries information and the read purpose is front-loaded, but the opening sentence is an unusually long multi-clause run-on describing the entire return payload, which is harder to scan than the terse 'Pass brand_id. Read-only. Errors: ...' that follows.

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 read tool with an output schema, annotations covering safety, and 100% schema coverage, the description supplies the missing pieces: prerequisite tracker, payload outline, error set, and default-week behavior. Nothing an agent needs before invoking it is absent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds framing beyond the schema by tying the optional week parameter to the payload shape — omitting it returns the latest stored week 'in full' along with the change from the previous stored week — and by restating the brand_id requirement in flow order.

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?

Opens with a specific verb and resource ('read a tracker from create_tracker') and then enumerates exactly what comes back: brand, rivals, prompts with ids, every stored week with mention/citation share, plus one week in full. This is far more specific than the sibling names add_round/create_tracker and lets an agent tell read from write without opening a 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?

It states the precondition (a tracker produced by create_tracker, whose brand_id must be passed) and implies the read counterpart to add_round. It does not explicitly state when to prefer this over sibling read-ish tools such as score_answer_share or get_feedback_reply, so it stops short of full routing 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavior beyond that: results are ranked best-match-first and the empty-input case enumerates every tool. It says nothing about result limits or pagination, which keeps it off a 5.

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

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

Four short sentences, front-loaded with what the tool does and what it returns before the usage hint. Nothing is redundant given the description is the only place ranking and empty-input behavior are stated in prose.

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

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

For a discovery tool with an output schema and full annotation coverage, this covers purpose, inputs, ranking, return fields and the no-argument case. An agent has everything needed to decide to call it and to interpret the results.

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

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

Schema coverage is 100% and the schema already explains that task, query and keyword are searched together and that omitting all lists everything. The description's 'task or keyword' phrasing actually omits 'query', so it adds no meaning beyond the schema and is marginally less complete than it.

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

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

States a specific verb and resource ('Search the tools on this server') and adds the matching mode ('by task or keyword in plain words'). It also names what comes back (name, title, one-line summary, input fields), so an agent knows exactly what this tool produces versus the sibling action 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?

'Use it when you are not sure which tool here fits a task' gives a clear triggering condition, and 'With no words it lists every tool' covers the degenerate case. It does not state when *not* to use it or name an alternative, but no sibling here offers overlapping discovery functionality, so the gap is minor.

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?

The annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. Beyond that, the description discloses the domain-specific counting rules that would otherwise be invisible: a repeated prompt is not a mention (prompt words are stripped), and a link counts only if it resolves to the brand domain. It also summarizes the output composition (mention share, citation share by engine and buyer prompt, rival frequency, sites cited, fix list), which is more than the annotations convey.

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 most important constraint ('never queries an AI engine') is front-loaded, and the sentence order moves logically from limitation, to trigger, to inputs, to outputs, to counting rules. It is dense but not padded, though the opening pronoun 'It' is a slightly weak anchor and the output enumeration in the middle sentence is long enough to compress.

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 non-trivial - nine parameters, one required, with a batch 'answers' array and competitor objects - and the description covers the essential contract: what to supply, what it computes, and the two counting rules that determine correctness. Because an output schema exists, the return-value summary is a bonus rather than a gap; only the answer-versus-answers choice and alias handling remain underspecified.

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 does add light grouping guidance - 'Pass the brand, its domain, rival names and every answer in answers (each with its prompt, engine and source links)' - which implicitly distinguishes the single-answer and batch paths, but it does not explain when to prefer 'answer' over 'answers', how aliases interact with matching, or what 'buyer prompts' implies for structuring the input.

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

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

The description gives a specific verb and resource ('score brand share' over pasted AI answers) and enumerates the exact questions it answers: whether the brand was named or linked, what share it got, which rivals or sites were chosen, and what to do. It also states up front what it is not ('never queries an AI engine'), which no sibling tool ('create_tracker', 'add_round') overlaps with, so an agent can route unambiguously.

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?

Trigger conditions are explicit and concrete: 'Call this when a user pastes answers from ChatGPT, Perplexity, Google AI Mode, Claude or another AI assistant' and asks one of four listed question types. It also handles the negative case with a fallback action - if answers are not pasted, ask for them and their source links first - which prevents the agent from invoking prematurely or fabricating inputs.

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?

Adds substantial context beyond the annotations: it returns a ticket id, feedback is explicitly not a chat and nothing in it is executed, and links/emails/phone numbers are stripped with nothing stored about the caller. That privacy and no-execution disclosure is genuinely useful given openWorldHint=true and readOnlyHint=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?

Front-loads what the tool sends, then what to pass, then what it returns, in three dense sentences with no filler. Every clause carries actionable 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?

Covers purpose, the enumerated kinds, the optional tool/error inputs, the 1000-character bound, the return value (ticket id), and privacy handling. With an output schema present, nothing further is required for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the kind enum. The description restates the message length limit and the optionality of tool/error ('if you know them') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Send feedback, a bug report or a tool request to the maintainers of the tools on this server') and enumerates the concrete situations (missing tool, stale data, broken/wrong answer). It is clearly distinguishable from the read-side sibling get_feedback_reply.

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

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

Gives clear triggering conditions for each kind (need_tool, need_data, bug, other) and tells the agent to include the tool name and error text when known. It does not explicitly name the alternative get_feedback_reply or state when NOT to use this tool, so it falls short of full routing guidance.

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