ScoreStory

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the mutation/non-destructive profile is covered structurally. The description adds no behavioral context such as duplicate-name handling, permission requirements, or whether the theme is immediately visible to interviewers.

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 waste. It is efficient, though it may be underspecified rather than concise given the lack of usage and behavioral 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 simple three-parameter mutation with full schema coverage and annotations, the description is minimally adequate. However, it omits prerequisites, duplicate behavior, and what 'theme' means in this product context, leaving meaningful gaps for an agent deciding whether and how to call it.

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

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

Schema description coverage is 100%, so all three parameters (name, survey_id, description) are already documented with examples and constraints. The description only implies the survey scoping and does not add meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Add a theme') and scopes it to a survey, which distinguishes it from survey-level siblings like create_survey. It is clear but relies on the domain term 'theme' without explaining what a theme is beyond 'what the interviewer explores.'

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g., survey must already exist), and no reference to alternatives among siblings such as create_survey or get_survey. The phrase 'in this survey' only loosely implies the survey must pre-exist.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds that a link is returned, which is useful given no output schema, but says nothing about repeat calls producing duplicate links or how a link is later revoked.

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

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

Three short sentences, front-loaded with what is produced, then when to use it, then the return value. No filler and nothing buried.

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

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

For a simple four-parameter creation tool with full schema documentation and annotations, this covers purpose, selection criteria, and the return value. The only meaningful gap is lifecycle behavior around duplicate or revocable links.

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

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

Schema coverage is 100%, with label, max_uses, and expires_at all well documented in the schema including defaults and formats. The description adds no parameter guidance beyond what the schema already provides, 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: creating one link that many people can open to take a survey, and clarifies the anonymous-audience scope. It does not name a sibling, but the 'do not know who the participants are' framing implicitly separates it from targeted invitation tools like invite_participant.

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?

Explicit when-to-use with concrete scenarios (newsletter, QR code, intranet post), which is a clear selection criterion. It stops short of naming the alternative tool for known participants, so the routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is largely covered. The description adds genuine value beyond them by clarifying that creation alone has no external effect and that distribution is a separate explicit step. It does not mention whether the survey is editable or deletable afterwards.

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-loaded with the action and followed by the constraint and the alternatives. Nothing is padding.

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

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

With 8 parameters fully documented in the schema and no output schema, the description need not explain fields or return values. The one minor gap is that it does not mention that the created survey's identifier is what you pass to the sharing tools, but the workflow intent is complete enough to call 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%, with metrics, locales, scale constraints and anonymity all documented inline. The description adds no parameter-level meaning of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a new survey") and immediately separates it from the downstream sharing siblings by noting nothing is sent yet. An agent can distinguish this creation step from create_shared_link/invite_participant 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?

Explicitly names the follow-up tools (create_shared_link, invite_participant) and the condition under which they are needed, which gives clear sequencing guidance. It stops short of stating when a survey should be created at all, but the context is unambiguous for this 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the return shape (score, breakdown, conclusion, ranked themes with sentiment counts and quotes), which is genuinely useful given there's no output schema, but it says nothing about pagination, result size, or how the period parameter affects aggregation.

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

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

A single front-loaded sentence that leads with what the tool delivers, then enumerates components cleanly. No filler, though the trailing clause about quotes is somewhat long.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly, listing each component. The main gap is any mention of how time filtering changes the aggregation, but for a read-only results tool this is close to complete.

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

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

Schema description coverage is 100%, with both parameters fully documented including the period enum-like values and range syntax, so baseline is 3. The description adds no supplementary meaning about survey_id or period behavior, but none is needed.

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 conveys the resource (survey results) and enumerates exactly what comes back: headline score, breakdown, written conclusion, ranked topics with counts and quotes. It never uses an explicit verb like 'retrieve' and doesn't distinguish itself from sibling get_survey, but the content is specific enough that an agent knows precisely what this tool yields.

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 get_survey, get_topic_quotes, or read_transcript, all of which overlap with survey/topic data. The description lists outputs but gives no selection criteria or prerequisites, leaving the agent to infer routing from tool names alone.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context — that some fields can be locked once responses exist — but says nothing about error behavior for a nonexistent ID or the shape of the returned configuration.

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 front-loaded sentence that leads with the object and then enumerates the returned contents; each listed item is substantive configuration data rather than filler. Slightly list-heavy but efficient.

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

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

With no output schema, the description usefully enumerates the returned fields (metric and scale, language, goal, themes, breakdown properties, locked fields), which is what an agent needs to decide whether to call it. Only minor gaps remain around failure modes.

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

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

Schema description coverage is 100% and the single parameter even documents its source ('as returned by list_surveys or create_survey'). The description adds no further meaning about survey_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('full configuration of one survey') and enumerates the contents, which makes it clearly distinct from list_surveys, get_results, and create_survey without naming them. It stops short of explicitly contrasting with a sibling, so a 4 rather than 5.

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

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

Usage is only implied: an agent can infer this is the follow-up to list_surveys when the configuration of a single survey is needed. There is no explicit when-to-use/when-not-to-use statement or named alternative such as list_surveys for browsing many surveys.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that each quote carries a speaker score and stance, which is genuine payload context. It says nothing about ordering, whether quotes are sampled or exhaustive, or how the limit interacts with selection.

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 clause-dense sentence with no filler; the scoping ('one topic') and the provenance come first, then the returned fields.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so only partly: it names score and stance but not their ranges, the quote text field, or ordering/pagination behavior for the default limit of 12. For a read-only tool with fully described params this is adequate but leaves real gaps.

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 (limit, topic_id, survey_id) are already documented in-schema. The description mentions the topic scoping but adds no syntax, format, or edge-case detail beyond the schema, 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?

Names a specific resource (quotes for a single topic) and its provenance (from get_results), plus the distinguishing payload fields (speaker's score and stance). It separates this from get_results and read_transcript well, though it lacks an explicit verb and doesn't state that only one topic's quotes are returned per call.

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?

'from get_results' implies the prerequisite workflow (get a topic_id via get_results first), which is useful implied guidance. But there is no explicit when-to-use versus read_transcript (full transcript) or get_results (aggregate results), and no stated exclusions.

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 this is not read-only and not idempotent. The description adds important behavioral detail: no email is sent from this tool, and the return value is a private link. This goes beyond what annotations provide by clarifying the side effect and distribution expectation.

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, front-loaded with the core action and immediately followed by the key operational caveat (no email sent). No filler or redundancy.

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 no output schema, the description adequately explains what is returned (a private link) and the key behavioral constraint (no email sent). Annotations cover idempotency and mutation semantics. Minor gap: it doesn't discuss rate limits or repeated invocation effects, but that is secondary for a simple creation tool.

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

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

Schema description coverage is 100%, so all five parameters (name, email, survey_id, properties, external_id) are fully documented in the schema. The description does not add any parameter-specific guidance beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description says exactly what the tool does: 'Create a personal invitation for one participant and return their private link.' It specifies the resource (personal invitation), scope (one participant), and output (private link). This clearly distinguishes it from sibling create_shared_link, which would not be personal or per-participant.

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 explains how the link is meant to be used ('for you or the person to pass on') and explicitly notes that scorestory does not email the link, so the caller must distribute it via the survey's Invite page. It does not explicitly compare to alternatives like create_shared_link, but the context for when to use this tool is clear.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: results are ordered newest first, and name/email are only populated when the survey is not anonymous — a data-redaction rule an agent could not otherwise predict.

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

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

A single sentence that puts the resource first and then the returned fields and ordering; no filler, no restatement of the title.

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

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

For a two-parameter, non-destructive read with full schema coverage and no output schema, the description covers what is returned, how it is ordered, and the anonymity caveat. Nothing an agent needs to call it correctly or interpret the response 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 status parameter already enumerates started/completed/abandoned and explains the omit-for-everyone default, so the schema carries the parameter burden. The description adds nothing about parameter syntax or filtering semantics beyond what the schema states, which is the baseline case.

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

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

Names the resource and its scope precisely: respondents who started a given survey, with the fields returned and their ordering. It does not distinguish itself from nearby siblings such as get_results or read_transcript, so an agent must infer that this returns metadata about people rather than answers.

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 people who started this survey' — you call it to see who responded — but there is no explicit when-to-use, no statement of when to prefer get_results or read_transcript, and no prerequisites noted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that — default ordering (newest first) and the fields surfaced per survey — but says nothing about result size, pagination, or what happens in a workspace with many surveys.

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. The primary behavior and its key characteristics lead, with the usage guidance following immediately after.

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 input schema to explain and no output schema, the description carries the return-value burden and does so partly, naming four fields and the sort order. It remains silent on pagination or completeness of the list, which is the main residual gap.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no input is needed by framing it as a workspace-wide enumeration.

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

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

Specific verb and resource ('List every survey in the workspace') plus scope details (newest-first ordering, returned fields: metric, language, respondent count). The closing clause positions it relative to survey-specific siblings, so an agent can distinguish it from get_survey/get_results 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?

Explicitly states when to use it: 'to find the survey a person means before calling anything survey-specific', which establishes it as a discovery step preceding get_survey/get_results. It stops short of naming the alternative tools or stating when-not to use it, so it is clear context rather than a full routing rule.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable context by disclosing the returned components and flagging the personal-data sensitivity, though it does not discuss pagination or response 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?

Two tightly written sentences. The return contents are front-loaded, and the privacy warning follows immediately without waste.

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 tool with two fully described parameters and no output schema, the description supplies the essential return contents and a critical privacy constraint. Nothing an agent needs in order to call 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 coverage is 100%, with both survey_id and respondent_id fully documented including where the IDs come from. The description does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific resource and scope: one participant's full interview, listing score, conversation, summary, and topics. It implicitly distinguishes from aggregate siblings like get_results and get_topic_quotes, though it does not name alternatives 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?

Provides a clear privacy-driven condition: show it only when the person asked for it. That is a meaningful when-to-use rule, but it does not explicitly compare this tool to alternatives such as get_results or get_topic_quotes.

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